6.7 贡献流程与代码规范

2 months ago
53374dd

贡献流程与代码规范

欢迎提交缺陷修复、测试、文档和功能改进。贡献前阅读仓库 LICENSE；本项目允许协议范围内使用和修改，但不是标准开源许可证，并限制派生版本再分发。

开始贡献

  1. 从仓库当前默认分支创建短生命周期分支。
  2. 初始化 admin-webui 子模块。
  3. 先为缺陷补充失败测试，或为功能写明行为和兼容范围。
  4. 保持提交聚焦，不夹带生成物、个人配置或无关格式化。
  5. 提交 PR/MR，说明背景、方案、测试和升级影响。

不要假定仓库存在固定 develop 分支；以托管平台当前默认分支和维护者要求为准。

提交前检查

GOWORK=off go test ./...
GOWORK=off go vet ./...

cd admin-webui
pnpm run check:type
pnpm run test:unit
pnpm run build:antd --filter='!./docs'

只修改后端时可以省略不受影响的前端构建，但涉及 API DTO、路由或管理页面时必须同时检查两端。

Go 规范

  • 仅对修改过的 Go 文件执行 gofmt。
  • 错误要处理、包装或向上返回，不静默吞掉。
  • Controller 保持薄；Service 不依赖 HTTP Context；DAO 不包含页面逻辑。
  • 数据访问显式带工作区条件，列表分页限制不超过接口定义。
  • 使用参数绑定/GORM，禁止把不可信输入拼进 SQL、表名或排序表达式。
  • 日志使用当前 gsr.Logger/golog API，不输出秘密。

API 与前端规范

  • 路径和 JSON 字段保持 snake_case，与后端 DTO 一致。
  • 业务请求集中在 admin-webui/apps/web-antd/src/api，组件不直接散落调用 axios。
  • 后端返回统一 {code,message,data}；CSV、HTML、重定向等明确例外单独处理。
  • 新公开接口需评估认证缺失、速率限制、CSRF/滥用和隐私风险。

数据库变更

  • 新增同版本的 MySQL、PostgreSQL、SQLite 迁移。
  • 不修改已发布迁移，不依赖 GORM AutoMigrate 修复生产结构。
  • 迁移需要在空库和已有数据副本上验证 Up；能安全回滚时同时验证 Down。
  • 大表回填给出时间、锁、并发和失败恢复说明。

提交信息

推荐 Conventional Commits，例如：

fix(short-link): correct workspace-scoped duplicate lookup
docs(api): document signature canonicalization
test(migration): cover sqlite upgrade path

安全报告

不要在公开 Issue 中粘贴可利用的生产 Secret、真实用户数据或未修复漏洞细节。先通过仓库维护者提供的私有渠道联系；提交修复时使用合成数据。

相关章节：添加新功能、测试与调试。