主要内容：该项目的基本文档，目的啥的，先随便写写。



# 1 大致设想

1. 解决yapi的功能过少问题。
2. 为前端提供mock接口，为后端提供测试请求。
3. 为接口关联说明文档，可能的话可以直接关联链接。
4. 说明文档可以加版本。

# 2 基本文档

由AI快速生成。

## 1. 项目背景

在前后端分离开发的模式下，接口是协作的核心。
常见痛点：

* 前端需要 mock 数据，后端接口未完成时进度受阻。
* 接口文档更新不及时，导致前后端对接出错。
* 接口修改后缺乏历史追溯机制，难以管理版本。
* 测试阶段需要统一的接口调试和用例管理。

**目标：**
打造一个面向团队的接口管理平台，支持接口定义、mock、测试、历史追踪与文档生成。

---

## 2. 项目目标

* 提供接口的统一管理入口
* 支持前后端协作中的 **mock 数据**
* 支持后端开发和 QA 的 **测试请求**
* 接口文档可视化、可导出（Markdown/HTML）
* 保留接口 **编辑历史**，可版本回溯
* 支持团队协作和权限控制

---

## 3. 核心功能模块

### 3.1 接口管理

* 创建 / 修改 / 删除 接口定义
* 字段：名称、路径、方法、请求参数、响应体、状态码
* 支持分组、标签、搜索

### 3.2 Mock 数据

* 每个接口可配置 **mock 规则**（静态 JSON / 随机生成规则）
* 前端可直接调用 Mock API
* 支持环境切换（开发 / 测试 / 生产）

### 3.3 测试请求

* 内置 API 调试工具（类似 Postman）
* 保存测试用例
* 自动化运行测试请求，查看结果

### 3.4 历史版本管理

* 每次编辑接口自动生成版本记录
* 可回溯到任意版本
* 对比不同版本差异

### 3.5 文档管理

* 自动生成 Markdown/HTML 文档
* 支持按分组导出
* 支持在线文档浏览

### 3.6 用户与权限

* 用户管理：成员、角色、权限
* 行级安全（不同项目/团队隔离）
* 审计日志：谁改了什么接口

---

## 4. 技术设计（初稿）

### 4.1 技术栈

* **后端**：Kotlin
* **数据库**：PostgreSQL 16（利用 JSONB、全文搜索、行级安全）
* **前端**：React
* **Mock 服务**：需要确定 Ktor 的 Client 的可用性。

### 4.2 数据库设计（PostgreSQL 视角）

#### 表：`api_endpoints`

| 字段               | 类型        | 说明                  |
| ---------------- | --------- | ------------------- |
| id               | UUID      | 主键                  |
| name             | text      | 接口名称                |
| path             | text      | 接口路径                |
| method           | text      | GET/POST/PUT/DELETE |
| request\_schema  | jsonb     | 请求参数定义              |
| response\_schema | jsonb     | 响应体定义               |
| group            | text      | 所属分组                |
| version          | int       | 当前版本号               |
| created\_at      | timestamp | 创建时间                |
| updated\_at      | timestamp | 更新时间                |

#### 表：`api_versions`

| 字段          | 类型        | 说明     |
| ----------- | --------- | ------ |
| id          | UUID      | 主键     |
| api\_id     | UUID      | 所属接口   |
| version     | int       | 版本号    |
| snapshot    | jsonb     | 接口定义快照 |
| created\_at | timestamp | 保存时间   |

#### 表：`api_mock`

| 字段          | 类型        | 说明      |
| ----------- | --------- | ------- |
| id          | UUID      | 主键      |
| api\_id     | UUID      | 所属接口    |
| mock\_data  | jsonb     | mock 配置 |
| created\_at | timestamp | 创建时间    |

#### 表：`api_tests`

| 字段          | 类型        | 说明   |
| ----------- | --------- | ---- |
| id          | UUID      | 主键   |
| api\_id     | UUID      | 所属接口 |
| request     | jsonb     | 测试请求 |
| response    | jsonb     | 测试结果 |
| created\_at | timestamp | 测试时间 |

---

## 5. 使用 PostgreSQL 的特别设计点

* **接口定义和历史版本用 `JSONB` 存储** → 灵活应对结构变化。
* **全文搜索** → 支持在接口文档里按关键字搜说明。
* **部分索引** → 只对 `active = true` 的接口加索引，提高查询效率。
* **行级安全（RLS）** → 保证不同团队/项目的数据隔离。
* **LISTEN/NOTIFY** → 当接口有更新时，通知前端实时刷新。

---

## 6. 未来扩展

* 与 CI/CD 集成，自动测试接口可用性
* 接口调用频率统计、性能监控
* GraphQL/OpenAPI 导入导出
* 权限细分（只读、编辑、审核）
* 插件化（mock 生成器、测试脚本扩展）

# 3 MVP

> MVP = Minimum Viable Product

## 1. MVP 目标

* 前后端有一个共同的接口定义库
* 前端能拿到 Mock 数据
* 后端能看到接口定义并做测试
* 团队能查阅 Markdown 文档

---

## 2. MVP 核心功能

### 2.1 接口管理

* 新建 / 编辑 / 删除接口
* 必填信息：

  * 名称
  * 路径（/api/v1/articles）
  * 方法（GET/POST/PUT/DELETE）
  * 请求参数（jsonb 存）
  * 响应体定义（jsonb 存）

### 2.2 Mock 数据

* 每个接口允许配置一份 Mock JSON
* 提供 Mock API 入口，前端可直接调用（例如 `/mock/api/v1/articles`）

### 2.3 测试请求

* 在后台界面手动填写参数 → 发请求 → 返回结果展示
* 保存最近一次的请求数据和响应结果（方便回溯）

### 2.4 文档生成

* 自动生成接口列表（Markdown 格式）
* 支持导出单个接口的 Markdown 文档
* Web 界面支持在线预览

---

## 3. 非 MVP（后续迭代）

* 接口历史版本管理
* 接口编辑 diff 对比
* 用户 & 权限管理
* 自动化测试用例
* 项目/分组多维度管理
* CI/CD 集成

---

## 4. 数据库设计（PostgreSQL 16）

### 表：`api_endpoints`

| 字段               | 类型        | 说明        |
| ---------------- | --------- | --------- |
| id               | UUID      | 主键        |
| name             | text      | 接口名称      |
| path             | text      | 接口路径      |
| method           | text      | HTTP 方法   |
| request\_schema  | jsonb     | 请求参数定义    |
| response\_schema | jsonb     | 响应体定义     |
| mock\_data       | jsonb     | Mock JSON |
| created\_at      | timestamp | 创建时间      |
| updated\_at      | timestamp | 更新时间      |

### 表：`api_tests`

| 字段          | 类型        | 说明   |
| ----------- | --------- | ---- |
| id          | UUID      | 主键   |
| api\_id     | UUID      | 对应接口 |
| request     | jsonb     | 请求数据 |
| response    | jsonb     | 响应数据 |
| created\_at | timestamp | 创建时间 |

---

## 5. 技术选型建议

* **后端**：Ktor (Kotlin)
* **数据库**：PostgreSQL 16
  * `jsonb` 存储请求/响应/Mock
  * 索引：`(path, method)` 唯一索引
* **前端**：简单的 React/Vue 页面
* **Mock 服务**：后端直接暴露 `/mock/*` 路径

---

## 6. 交互流程示例

1. **后端开发** 新建接口 `/api/v1/articles`，定义请求和响应结构。
2. **前端开发** 在 Mock 模块写入示例数据：

   ```json
   {
     "id": 1,
     "title": "Hello PG",
     "content": "PostgreSQL is awesome!"
   }
   ```

   前端即可调用 `/mock/api/v1/articles` 获取该数据。
3. **测试** 在后台填写参数，发送请求到实际后端服务，查看返回值。
4. **文档** 自动生成接口 Markdown：

   ```markdown
   ### GET /api/v1/articles
   - **请求参数**: {...}  
   - **响应示例**: {...}  
   ```

InterfaceManagement | 记录1

工作记录

实习每日记录

主要内容为 Go 在1.24之后所采用的新的 Map 底层数据结构 SwissTable 的原理记录。



Go 在2025年2月11日发布了新版本1.24.0，里面比较重大的更新就是**支持弱指针**和**将 map 的默认底层实现替换为 SwissTable**。后者是这篇记录的主题，前者稍微记录一下：

### 1 弱指针（weak 包）

> 官方文档：https://pkg.go.dev/weak

弱指针（weak pointer），是一个存在了很久的概念。它是一种特殊的指针类型，它可以指向一个对象，但是不会增加该对象的引用计数，也不会阻止 GC 来回收该对象。如果弱指针指向的对象被 GC 回收，那么获取值会得到 nil。它的主要作用，一来是能够**防止指针循环引用**，从而使 GC 无法回收内存，继而导致内存泄漏；二来利用弱指针不会影响 GC 这一点，可以更好地**手动控制对象的生命周期**（个人认为后者作用会更明显）。

### 2 在 SwissTable 之前

map，或者叫哈希表（目标是读写时间复杂度`O(1)`的键值对存储结构），都是由两个部分构成：哈希函数，存储结构。虽然理想中的哈希函数，是应该不存在哈希碰撞，并且哈希值的每一位出现概率都是均等的。但是这毕竟是理想，现实里，存储结构也要面对哈希碰撞的问题。在 SwissTable 之前，解决哈希碰撞的存储结构方案有这么两种（也是八股常客）：

- 开放定址法：如果将存储结构看作一个数组，值存在数组上（权且管这个位置叫 slot），那么在发生哈希碰撞后，就会已存在的值的存储位置向后寻找（按寻找的方式，还有其他的方法。特别地，向后寻找的被称为线性探测法），直到能够找到存储的 slot。
- 链表法：仍然将存储结构看作一个数组。在发生哈希碰撞后，所有发生哈希碰撞的值会以链表的形式存在对应的 slot 上。

> Go 在 SwissTable 之前，我认为 Map 使用的方式算是加强版的，混合了部分链表法思路的开放定址法，详见https://www.misaka19327.cc/post/104

### 3 SwissTable

SwissTable 首次被提出是在2017年的 CppCon 大会上，在2022年被字节提 issue，建议使用它作为 Map 的底层数据结构。

SwissTable 的核心思想仍然是**改进线性探测法**，只是将 slot 的关键信息提取出来作为元数据进行读写，比直接读取整个 slot 更快。

#### 3.1 结构

SwissTable 的结构如图：

![image.png](https://www.misaka19327.cc/static/img/ed26df924e0facc32487813af0ca8e6b.image.png)

（对实际内存进行简化，看个意思）

SwissTable 主要由两部分构成：Control Bytes 和对应的 slots 数组。其中，Control Bytes 的每个字节都对应后面的一个 slot，字节内部存储的值，一个是指示 slot 的状态，另外就是在 slot 有值时，存储其 hash 得来的特征值。

图里没有写出来的有两部分，一个是 Group。它不是一个具体的结构，而是由8（不支持 simd 指令的平台）/16（支持 simd 指令的平台）个连续的控制字节组成。按图中所得，对键进行哈希后得到的哈希值，前57位的值（偏移量）就用来决定 slot 位置，而 slot 对应的控制字节的位置之后的7/15个控制字节就是一个 Group。

另外一个是，按照上面的说明，当决定 slot 位置定到了 Control Bytes 的尾部时，对应的控制字节之后的控制字节们的数量可能不足以支撑一个 Group。所以，Control Bytes 尾部也会复制头部的信息。

:::info{title="simd 指令"}
单指令流多数据流（Single Instruction Multiple Data，SIMD）是一种采用一个控制器来控制多个处理器，同时对一组数据（又称“数据向量”）中的每一个分别执行相同的操作从而实现空间上的并行性的技术。
:::

#### 3.2 查

按照上面对 Group 概念的说明，可知一个键的哈希值是可以落到一个长为8/16的 Group 上的，之后就是怎么找到对应的 slot。如果不存在哈希碰撞，那皆大欢喜，第一个控制字节所对应的 slot 就是要找的值。如果存在哈希碰撞，按照线性探测法，应该是对 Group 中的每个控制字节所对应的 slot 都挨个取出来比较 key。但是 SwissTable 在这里做了优化。它利用了 simd 指令并行计算的特点，将特征值和16个控制字节同时进行比较，得到的16个字节再压缩为 uint32，直接取尾部0的数量，即可得到要找的 slot 的位置。如果当前 Group 没能找到值，那么会顺序移动到下一个 Group，再一次整体比较，直至找到对应值或到结束位。

![image.png](https://www.misaka19327.cc/static/img/12c86be7286e75219533ac875901eddb.image.png)

（H2 即为特征值）

事实上，SwissTable 会首先过滤掉特征值不同的控制字节，再利用上述的方法快速找到要检查的 slot 位置。如果检查完第一个 slot 发现 key 不对，那么就可以将 uint32 的结果的检查完的 slot 所对应的1用位运算置零，再次计算尾随0的数量，即可找到下一个要检查的 slot。

增删的步骤基本上和查是差不多的，都是按这个方法定 Group，如果 Group 已满/没找到就顺延到下一个 Group，直到找到空 slot/目标键值对，写入数据/释放数据，并且修改对应的控制字节。

#### 3.3 结束

我认为，SwissTable 能够和 Go 原来的 Map 拉开差距，主要有几个点：

1. SwissTable 利用这个 simd 指令，使得每次找数据的时候都是同时批量地找，比原来的 Map 在 bucket 里的 tophash 找快。并且用的是位运算，比等值比较快。当然，如果不支持 simd 指令，那么性能也会有所下降。
2. 内存紧凑，比起原来的 Map，同一哈希值下的 bucket 是链表组织（内存松散），能够提高缓存命中率（对 CPU 来说）。

> Go runtime 下，原来的 map.go 变成了 map_swiss.go 和 map_noswiss.go，原来的实现还保留着，应该是可以通过 go build 的参数使用原来的底层结构。只是 map_swiss.go 没看懂，不好看源码了，主要是我找不到它的 linkname 链接的目标是谁。

Go底层/特性解析 | 新Map - 关于 SwissTable

主要内容：该项目的目的，技术选型，表结构啥的。先随便写写，反正也不是很急。



### 1 综述

鉴于我目前算是终于找到实习了，并且按实习的时间来看，如果不加班的话我的空闲时间是固定的，所以我想要先启动这个项目。

> 回来二编的时候，现在来看我都已经稳定下来了，都准备找房子租了，实习期已点没动是有点绷不住。

该项目的起因是因为我之前每天手动去收集同人帖实在有点顶不住，而且收集的效果也略显不足：没法搜索，没法排序筛选，没法看赞量，没法自动更新。其实我寒假中想要利用 KMP 上线的那个增强版本的 wasm 网页就是这个原因的产物，但是那个框架问题太多、加载太慢、并且没有利用多平台的必要，因此只好放弃。

经过上一次的尝试之后，我决定一方面还是采用稳定的框架来做，另一方面是让用户也有能力去提交同人信息。这次我的目标是搭建一个前后端分离的网站，后端会自动获取新帖和点赞量，前端采用流行的框架，达成搜索筛选排序等等的效果。看看能不能在六月份之前上线。

主要技术栈就是后端的 Ktor，PostgreSQL，redis 三件套。其中两个我都不是很熟悉，原因么一方面是对 Kotlin 的偏向和对其后端方向的发展有所好奇，另一部分是想要通过这个项目来接触更多的技术栈。

> 数据库改用H2，看到 Exposed 框架推荐有点想试试。

前端我想用 react 试一下，主要是对 TypeScript 感兴趣。让 Cursor 来主写，我补充吧。设计最好还是 material 风格，没有好的组件库再想办法。

（这个系列主要记后端部分，前端部分会再开一个新的分类去记录）

### 2 目标功能

1. 针对贴吧，会自动获取新帖，刷新老帖子的点赞量。
2. 得有一个用户注册的系统，以防无限制提交同人信息。
3. 有一个审核的功能，经过管理员的确认信息才能上去。
4. 同人信息大致按表格的形式展现，提供搜索，按点赞量排序，按标签筛选，对同人信息进行标记和记录的功能。
5. 前端我想尽量还是统一风格去做。
6. 防大量请求，我看看能不能在 ngingx 做反向代理的时候加点时间限制。
7. 因为每天都有部分帖子产生，所以需要辨认这些帖子是否为同人帖。用户可以以自愿的形式做这部分任务，记录贡献条目数。
8. 加评论？加评论的话我怕域名申请过不去，这部分先保留吧，日后再看看能不能上。
9. 用户可以提问，问题和回答必须过审核。

所以系统大致分这么几个模块：

1. 同人文信息模块：针对同人文信息的增删改查、自动获取同人文信息、用户提交的同人文信息维护。
2. 用户模块：注册、登录、令牌刷新这一块。角色就三种：超管、管理员、用户。
3. 问题模块：用户提问、回答关联和维护。
4. 审核模块：提交信息、提问、回答都交给管理员进行审核。

其他要加的就，日志、发邮件、数据库备份、剩下应该没啥了，想起来再加。

### 3 表结构设计