184 lines
6.0 KiB
Markdown
184 lines
6.0 KiB
Markdown
---
|
||
tags: []
|
||
aliases:
|
||
- 🔌 AI 辅助 API 定义方法论 (v1.0)
|
||
date created: 星期日, 十二月 7日 2025, 11:43:04 晚上
|
||
date modified: 星期日, 十二月 7日 2025, 11:44:30 晚上
|
||
---
|
||
|
||
# 🔌 AI 辅助 API 定义方法论 (v1.0)
|
||
|
||
**核心理念:**
|
||
|
||
1. **DTO 先行:** 先定义输入 (Request) 和输出 (Response) 的数据结构，再写业务逻辑。
|
||
2. **注释即文档:** 利用 AI 自动生成繁琐的 Swagger 注释 (`@Summary`, `@Param`…)。
|
||
3. **契约可视化:** 在写第一行逻辑代码前，先能在 Swagger UI 上看到接口定义。
|
||
|
||
---
|
||
|
||
## 阶段一：API 资源设计 (Design)
|
||
|
||
**目的:** 确定 URL 路径、HTTP 方法和 JSON 数据结构，确保符合 RESTful 规范。
|
||
|
||
### 🤖 通用 Prompt (复制使用)
|
||
|
||
```Markdown
|
||
你现在是我的 **API 架构师**。
|
||
我们已经完成了数据库设计，现在需要设计 `{业务模块}` (例如: User) 的 API 接口。
|
||
|
||
**输入上下文:**
|
||
1. **业务实体:** `{粘贴 User 的 Entity 代码或 SQL}`
|
||
2. **功能需求:** 注册、登录、获取个人资料、更新资料。
|
||
|
||
**请输出 API 设计方案 (表格形式):**
|
||
1. **Method:** GET/POST/PUT/PATCH/DELETE
|
||
2. **Path:** URL 路径 (使用 RESTful 风格, 如 `/api/v1/users/:id`)
|
||
3. **Request Body:** 关键字段 (JSON 示例)
|
||
4. **Response:** 成功返回的数据结构 (JSON 示例)
|
||
|
||
**设计原则:**
|
||
- 使用统一的响应信封: `{ "code": 200, "msg": "success", "data": ... }`
|
||
- 更新操作区分 PUT (全量) 和 PATCH (局部)。
|
||
- 敏感字段 (密码) 绝对不能出现在 Response 中。
|
||
```
|
||
|
||
---
|
||
|
||
## 阶段二：生成 DTO 结构体 (Contract Definition)
|
||
|
||
**目的:** 将 JSON 设计转化为 Go 结构体。这是前后端交互的**法律条文**。
|
||
|
||
**工程位置:** `internal/api/request/` (入参) 和 `internal/api/response/` (出参)。
|
||
|
||
### 🤖 通用 Prompt (复制使用)
|
||
|
||
```Markdown
|
||
设计确认通过。请基于上述设计，生成 Go 语言的 **DTO (Data Transfer Object) 结构体**。
|
||
|
||
**技术约束:**
|
||
1. 使用 `gin` 的 binding 标签进行参数校验 (如 `binding:"required,email"`).
|
||
2. 使用 `json` 标签定义字段名 (camelCase).
|
||
3. **分离 Request 和 Response:** 不要直接复用数据库 Entity，必须定义独立的 DTO。
|
||
|
||
**输出代码要求:**
|
||
- `UserRegisterReq` (包含 Email, Password, ConfirmPassword)
|
||
- `UserLoginReq`
|
||
- `UserProfileResp` (不含密码，转换时间格式)
|
||
|
||
请直接输出 Go 代码，放在 package `user_dto` 下。
|
||
```
|
||
|
||
---
|
||
|
||
## 阶段三：生成 Handler 骨架与 Swagger 注释 (Implementation Skeleton)
|
||
|
||
**目的:** 这是一个“体力活”。AI 最擅长帮我们要写几十行的 Swagger 注释。
|
||
|
||
**工程位置:** `internal/user/handler.go`
|
||
|
||
### 🤖 通用 Prompt (复制使用)
|
||
|
||
```Markdown
|
||
现在请生成 Gin Handler 的**代码骨架**，并附带完整的 **Swagger 注释**。
|
||
|
||
**输入:**
|
||
DTO 结构体已定义: `UserRegisterReq`, `UserProfileResp`...
|
||
|
||
**输出要求:**
|
||
1. **Swagger 注释:** 必须包含 `@Summary`, `@Tags`, `@Accept json`, `@Produce json`, `@Param`, `@Success`, `@Router`。
|
||
2. **Handler 签名:** 接收 `*gin.Context`。
|
||
3. **参数绑定:** 在 Handler 内部生成 `ShouldBindJSON` 代码块。
|
||
4. **占位返回:** 暂时直接返回 Mock 数据或 `http.StatusOK`，**不要写具体的 Service 业务逻辑**。
|
||
|
||
**示例注释格式:**
|
||
// Register
|
||
// @Summary 用户注册
|
||
// @Tags User
|
||
// @Accept json
|
||
// @Produce json
|
||
// @Param request body user_dto.UserRegisterReq true "注册信息"
|
||
// @Success 200 {object} app.Result{data=user_dto.UserProfileResp}
|
||
// @Router /api/v1/auth/register [post]
|
||
func (h *UserHandler) Register(c *gin.Context) { ... }
|
||
```
|
||
|
||
---
|
||
|
||
## 🏗️ 工程落地操作指南 (How to Execute)
|
||
|
||
### 1. 文件安放位置
|
||
|
||
不要乱放，严格遵守目录结构：
|
||
|
||
```Plaintext
|
||
internal/
|
||
├── api/ # [Contract Layer] 存放 DTO
|
||
│ ├── request/ # 入参结构体
|
||
│ │ └── user_req.go
|
||
│ └── response/ # 出参结构体
|
||
│ └── user_resp.go
|
||
└── user/ # [Domain Layer]
|
||
└── handler.go # 控制器 (含 Swagger 注释)
|
||
```
|
||
|
||
### 2. 实操步骤 (SOP)
|
||
|
||
#### Step 1: 定义 DTO (The Contract)
|
||
|
||
- 运行阶段二的 Prompt。
|
||
- 将代码复制到 `internal/api/request/user_req.go`。
|
||
- **这一步完成了，就代表你和前端的接口契约签好了。**
|
||
|
||
#### Step 2: 编写 Handler 骨架 (The Skeleton)
|
||
|
||
- 运行阶段三的 Prompt。
|
||
- 将代码复制到 `internal/user/handler.go`。
|
||
- 确保此时代码能编译通过（缺少 Service 调用没关系，先留空）。
|
||
|
||
#### Step 3: 生成 Swagger 文档 (Generate)
|
||
|
||
这是验证的关键一步。我们需要使用 `swag` 工具扫描你的注释并生成 JSON 文档。
|
||
|
||
**在终端执行:**
|
||
|
||
```Bash
|
||
swag init -g cmd/server/main.go -o docs
|
||
```
|
||
|
||
_(注意: `-g` 指向你的 main 函数入口，swag 会从那里开始递归扫描)_
|
||
|
||
#### Step 4: 启动服务并验证 (Verify)
|
||
|
||
- 运行 `go run cmd/server/main.go`。
|
||
- 打开浏览器访问 `http://localhost:8080/swagger/index.html`。
|
||
- **你看到的界面，就是你刚刚定义的“接口合同”。**
|
||
|
||
---
|
||
|
||
## 💡 常见问题与技巧
|
||
|
||
**Q: 为什么不直接用 Entity 作为 Response？**
|
||
|
||
- **A:** **千万别这么做。** Entity 包含 `password_hash`，包含 `deleted_at`，这些都不该给前端。DTO 让你有精准控制返回字段的权利。
|
||
|
||
**Q: Swagger 注释太难写了，容易写错格式。**
|
||
|
||
- **A:** 这就是为什么要用 AI 的原因。**永远不要手写 Swagger 注释**。把 Handler 代码发给 AI，对它说：“_请帮我补全 Swagger 注释，参数是 X，返回值是 Y_”。
|
||
|
||
**Q: 接口变了怎么办？**
|
||
|
||
- **A:**
|
||
|
||
1. 修改 DTO (Go Struct)。
|
||
2. 让 AI 更新 Handler 里的 Swagger 注释。
|
||
3. 运行 `swag init`。
|
||
4. 文档自动更新。
|
||
|
||
---
|
||
|
||
**总结你的下一步行动:**
|
||
|
||
1. **DTO 设计:** 使用 Prompt 生成 `User` 相关的 Request/Response 结构体。
|
||
2. **骨架生成:** 使用 Prompt 生成带有 Swagger 注释的 `UserHandler`。
|
||
3. **文档验证:** 运行 `swag init` 并在浏览器中确认接口文档无误。
|