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

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
   - **请求参数**: {...}  
   - **响应示例**: {...}