cf_Ghbf

Appearance

代码规范 ​

完整规范见仓库 server_api/docs/CODE_STYLE.md，本页为要点摘要。

后端 Go ​

分层（强制） ​

  • Controller 只做三件事：ShouldBind → 调 logic → response.OK/Fail；
  • Controller 必须把 *gin.Context 传入 logic，登录信息（claims）、IP、UA 在 logic 层获取；
  • Logic 负责业务规则、事务、缓存维护，不直接返回 Model，接口响应在 resp 中重新定义；
  • Param / Resp 按功能拆分文件（user.go、menu.go…），禁止合并为单一 param.go / resp.go。

结构体 Tag ​

go
type UserSaveReq struct {
    ID       uint   `json:"id" comment:"主键ID"`
    Username string `json:"username" comment:"登录账号"`
    Status   int    `json:"status" binding:"omitempty,oneof=1 2" comment:"状态"`
}
  • JSON 字段统一 snake_case；GET 查询参数补 form:"..."；
  • 每个字段写 comment:"..." 中文注释，作为接口文档与前端类型的事实来源；
  • 请求以 Req 结尾，响应以 Res / Item 结尾，实体内嵌 BaseItem。

响应与错误 ​

  • 统一 response.OK / response.Fail，HTTP 恒为 200；
  • 业务码：0 成功、400 参数错误、401 未登录、403 无权限、500 业务失败、503 依赖不可用；
  • 参数绑定失败统一返回 CodeErrParams，不透传 Gin 原始错误；
  • 数据库错误用 pkg/dberror 识别（重复键 → 友好提示）。

安全边界 ​

  • 密钥类字段响应不返回，写入留空表示不修改；
  • 上传只存相对路径，地址按默认存储动态生成（upload.NormalizeFilePath / FileURL）；
  • 展示类脱敏统一走 pkg/mask（手机号 138****8001）；
  • 用户可控的排序字段必须白名单，禁止拼接 SQL。

提交前检查 ​

bash
gofmt -l .      # 不允许有输出
go vet ./...
go build ./...
go test ./...   # 有测试时

前端 Vue / TypeScript ​

  • 统一 request<T>() 请求封装（src/api/http.ts），禁止页面直接使用 axios；baseURL 来自 VITE_ADMIN_API_BASE_URL；
  • 类型集中在 src/types/<module>.ts，复用 ApiResponse / PageQuery / PageResult / TreeNode / BaseEntity；禁止 any；
  • 枚举集中在 src/enums，as const 对象 + 文案映射，数值与后端一致；
  • 页面放 src/views/<模块>/<页面>/index.vue，与后端菜单 path 对应；列表页与表单组件拆分；
  • <script setup lang="ts">、组合式 API、箭头函数；
  • 日期时间用 formatDateTime 格式化到秒；
  • 按钮权限 v-perm="'POST:/admin/user/add'"；
  • 明暗主题同时可用，样式复用 .page-card、.toolbar、.table-operations 与主题变量；
  • 富文本统一复用 src/components/RichTextEditor.vue，不得重复封装 WangEditor。

提交前检查 ​

bash
pnpm exec vue-tsc --noEmit
pnpm build

文档同步 ​

  • 新增或修改接口后同步 server_api/docs/admin_openapi.yaml（管理端）或 server_api/docs/api_openapi.yaml（用户端）；
  • 新增配置项同步 config/config.go、config.example.yaml 与 README 配置表；
  • 每次发版更新 config.yaml 的 version 并新增 docs/update_doc/v{version}.md，详见发版说明。