mirror of
https://github.com/flipped-aurora/gin-vue-admin.git
synced 2026-10-11 03:49:29 +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>
90 lines
2.8 KiB
Markdown
90 lines
2.8 KiB
Markdown
# 后端分层约束
|
|
|
|
## 总原则
|
|
|
|
- 严格遵守 `Router -> API -> Service -> Model` 依赖方向
|
|
- 禁止跨层直接调用
|
|
- `enter.go` 作为组装与暴露入口，避免循环引用
|
|
|
|
## Model 层
|
|
|
|
- 数据模型优先继承 `global.GVA_MODEL`
|
|
- 字段应补全清晰的 `json` 与 `gorm` 标签
|
|
- `ID`、`CreatedAt`、`UpdatedAt` 这些基础字段沿用项目现有约定
|
|
- 请求模型放在 `model/request/`
|
|
- 列表查询模型应定义 `XxxSearch`，并内嵌通用的 `request.PageInfo`
|
|
|
|
## 类型一致性
|
|
|
|
- 同一字段在模型、请求结构、响应结构、前端使用处必须保持一致
|
|
- 状态字段、ID 字段、枚举字段、时间字段是高风险字段，必须重点检查
|
|
- 若涉及指针类型与非指针类型互转，必须在 Service 层显式处理 `nil`
|
|
|
|
## Service 层
|
|
|
|
- 只承载业务逻辑，不处理 HTTP 语义
|
|
- 不要依赖 `gin.Context`
|
|
- 函数应返回业务结果和 `error`
|
|
- 每个模块在 `service/` 下建立独立文件，并在 `service/enter.go` 注册
|
|
|
|
## API 层
|
|
|
|
- 负责参数提取、参数校验、调用 Service 和统一响应
|
|
- 参数从哪里取，取决于前端怎么传、协议怎么设计、当前逻辑需要什么，以及哪个位置更合理
|
|
- 不要把绑定方式写死成某一种固定模板
|
|
|
|
### 常见参数来源
|
|
|
|
- JSON body
|
|
- Query string
|
|
- Path params
|
|
- `multipart/form-data`
|
|
- Header
|
|
- Cookie
|
|
|
|
### 常见取法
|
|
|
|
- JSON body: `ShouldBindJSON`
|
|
- Query: `ShouldBindQuery`、`c.Query(...)`、`c.DefaultQuery(...)`
|
|
- Path: `c.Param(...)`
|
|
- form-data / file upload: `c.FormFile(...)`、`c.DefaultPostForm(...)`、`c.Request.FormValue(...)`
|
|
- Header: `c.GetHeader(...)`、`c.Request.Header.Get(...)`
|
|
- Cookie: `c.Cookie(...)`
|
|
|
|
### 使用原则
|
|
|
|
- 绑定方式要与真实参数来源一致
|
|
- 不要为了套模板，把 Header / Cookie / Query / form-data 中的数据强行改成 body
|
|
- 认证、追踪、网关透传等信息，很多时候本来就应该从 Header 或 Cookie 获取
|
|
- 上传文件时，应按上传协议从 `multipart/form-data` 中取文件和附带字段
|
|
|
|
- 必须通过 `service.ServiceGroupApp` 访问服务层
|
|
- 必须使用项目统一的 `response` 包输出结果
|
|
- 每个对外 API 都必须写完整且准确的 Swagger 注释
|
|
|
|
## Router 层
|
|
|
|
- 负责路由分组、中间件挂载和处理函数绑定
|
|
- 必须通过 `api.ApiGroupApp` 引用 API 层
|
|
- 每个模块在 `router/` 下建立独立文件，并在 `router/enter.go` 注册
|
|
|
|
## Initialize 层
|
|
|
|
插件或模块若需要初始化入口，至少关注以下职责：
|
|
|
|
- `gorm.go`: 表结构迁移
|
|
- `router.go`: 路由注册
|
|
- `menu.go`: 菜单与权限初始化
|
|
- `viper.go`: 配置加载
|
|
- `api.go`: API 注册
|
|
|
|
## Swagger 约束
|
|
|
|
对外 API 的 Swagger 注释至少要准确说明：
|
|
|
|
- 功能说明
|
|
- 请求参数
|
|
- 响应结构
|
|
- 路由路径
|
|
- 鉴权要求
|