mirror of
https://github.com/flipped-aurora/gin-vue-admin.git
synced 2026-09-26 22:31:17 +00:00
15e6e7685c
* feat: 调整AI工作模式，更符合harness基准 * feat: 添加BusinessDB字段到PluginInitializeGorm结构体，并增加相关测试用例 * [middleware/jwt.go]: fix #2192 issues bug * docs: add auto plugin design spec * chore: ignore worktrees directory * feat: 调整代码辅助能力至插件 * feat: 添加警告条组件，提示授权用户访问限制 * fix: 修正商业用途版权声明链接 * feat: 调整agent.md 更加节省token * fix: 修改casbin版本为v3 * feat: 更新JSONMap和JSONSlice类型，优化GORM数据类型处理 * feat: 添加数据库就绪通知机制，优化插件注册流程 * feat: 重构API路径和描述，优化代码生成器和模板配置分组 * feat: 优化 person 页面的 css 作用域限制 * feat: 更新 vite 至 vite8 * 新增：MCP工具为指定URL的角色ID授权 * fix: 增加文件名合法性检查，拒绝包含非法字符的文件写入 * chore: 更新CI配置，升级Node.js和Go版本，调整checkout和setup动作版本 * feat: 为数据库连接增加最大复用时间配置 * feat: 为各数据库连接配置增加最大连接生命周期设置 * feat: 更新插件注册逻辑并优化API和菜单组件的标签显示 * feat: 更新版本号至v2.9.2并添加新插件路径信息 --------- Co-authored-by: taincheng <zhangtc@gmail.com> Co-authored-by: Azir-11 <2075125282@qq.com> Co-authored-by: lanxi <1220lanxi@gmail.com>
104 lines
3.3 KiB
Markdown
104 lines
3.3 KiB
Markdown
# API 示例
|
|
|
|
## 这个文件负责什么
|
|
|
|
API 层负责接收 HTTP 请求、从合适的位置提取参数、调用 Service、统一返回响应，并补全 Swagger 注释。
|
|
|
|
## 什么时候应该这样写
|
|
|
|
- 新增对外接口
|
|
- 为某个模块补 CRUD 接口
|
|
- 需要统一响应结构和错误处理
|
|
|
|
## 核心原则
|
|
|
|
参数从哪里取，不是由“AI 习惯”决定，而是由下面几件事共同决定：
|
|
|
|
1. 前端怎么传
|
|
2. 接口协议怎么约定
|
|
3. 当前逻辑到底需要什么数据
|
|
4. 这个数据放在哪个位置更合理、更安全
|
|
|
|
也就是说，API 层不应该机械地一律使用 `ShouldBindJSON`，而应该先判断参数来源，再选择对应取法。
|
|
|
|
## 常见参数来源与推荐取法
|
|
|
|
- JSON body: `ShouldBindJSON`
|
|
- Query string: `ShouldBindQuery`、`c.Query(...)`、`c.DefaultQuery(...)`
|
|
- Path params: `c.Param(...)`
|
|
- `multipart/form-data`: `c.FormFile(...)`、`c.DefaultPostForm(...)`、`c.Request.FormValue(...)`
|
|
- Header: `c.GetHeader(...)`、`c.Request.Header.Get(...)`
|
|
- Cookie: `c.Cookie(...)`
|
|
|
|
## 推荐写法示例
|
|
|
|
下面这个示例演示的是 `POST + JSON body` 场景，所以这里使用 `ShouldBindJSON`。
|
|
|
|
```go
|
|
package system
|
|
|
|
import (
|
|
"github.com/flipped-aurora/gin-vue-admin/server/model/common/response"
|
|
systemReq "github.com/flipped-aurora/gin-vue-admin/server/model/system/request"
|
|
"github.com/gin-gonic/gin"
|
|
)
|
|
|
|
// GetOrderList
|
|
// @Tags Order
|
|
// @Summary 分页获取订单列表
|
|
// @Security ApiKeyAuth
|
|
// @accept application/json
|
|
// @Produce application/json
|
|
// @Param data body systemReq.OrderSearch true "分页和筛选参数"
|
|
// @Success 200 {object} response.Response{data=response.PageResult,msg=string} "返回列表、总数、分页信息"
|
|
// @Router /order/getOrderList [post]
|
|
func (o *OrderApi) GetOrderList(c *gin.Context) {
|
|
var pageInfo systemReq.OrderSearch
|
|
if err := c.ShouldBindJSON(&pageInfo); err != nil {
|
|
response.FailWithMessage(err.Error(), c)
|
|
return
|
|
}
|
|
|
|
list, total, err := orderService.GetOrderList(pageInfo)
|
|
if err != nil {
|
|
response.FailWithMessage("获取失败", c)
|
|
return
|
|
}
|
|
|
|
response.OkWithDetailed(response.PageResult{
|
|
List: list,
|
|
Total: total,
|
|
Page: pageInfo.Page,
|
|
PageSize: pageInfo.PageSize,
|
|
}, "获取成功", c)
|
|
}
|
|
```
|
|
|
|
## 为什么这样写
|
|
|
|
- API 层统一负责“取参数 + 校验 + 调 Service + 回响应”
|
|
- 取参数方式必须与真实数据来源一致，而不是套固定模板
|
|
- 例如：
|
|
- 登录、创建、更新这类通常来自 JSON body
|
|
- 列表筛选、分页、导出条件常来自 Query
|
|
- 上传文件通常来自 `multipart/form-data`
|
|
- 鉴权 token、特殊网关头、追踪信息常来自 Header 或 Cookie
|
|
- 成功 / 失败统一使用 `response` 包
|
|
- Swagger 注释让接口契约对前端和文档生成都可见
|
|
|
|
## 常见错误
|
|
|
|
- 在 API 层直接操作数据库
|
|
- 直接 `c.JSON(...)`，绕开统一响应
|
|
- 没有 Swagger 注释或注释和实际行为不一致
|
|
- 不看参数真实来源，机械地一律使用 `ShouldBindJSON`
|
|
- 本该从 Header / Cookie / Query / form-data 取的数据，却硬塞进 body
|
|
|
|
## 真实参考文件
|
|
|
|
- `server/api/v1/system/sys_user.go`
|
|
- `server/api/v1/system/sys_dictionary.go`
|
|
- `server/api/v1/system/auto_code_mcp.go`
|
|
- `server/api/v1/example/exa_file_upload_download.go`
|
|
- `server/utils/claims.go`
|