跳到主要内容

Contributing Guide (Jingyun Center Backend)

本指南是后端工程规范与协作流程的落地文档，适用于本仓库（Go/Kratos/Ent/protobuf 微服务架构）。请在提交代码前通读本文，并按文档要求执行本地校验。

目录：

  • 一、总体要求
  • 二、开发环境与依赖
  • 三、分支模型与提交规范
  • 四、代码风格与静态检查
  • 五、测试规范与覆盖率门禁
  • 六、API/IDL 与代码生成
  • 七、数据层与数据库规范（Ent/SQL）
  • 八、消息队列与异步
  • 九、安全与合规
  • 十、可观测性与运维要求
  • 十一、PR 门禁与评审清单
  • 十二、变更类型与发布
  • 附录：本地常用命令

一、总体要求

  • 语言版本：Go 1.25.4（统一版本）
  • 依赖管理：Go Modules；禁止 GOPATH 模式
  • 代码生成：通过各服务 Makefile 统一生成，不得手动修改生成文件
  • 持续集成：本地必须先通过 lint + test + 生成校验，再提交 PR

二、开发环境与依赖

  • 基础依赖：protoc、Docker、Docker Compose、make
  • 本地启动基础设施（如需）：
    • docker-compose -f deployments/docker-compose.local.yml up -d postgres-jingyun redis-jingyun consul rabbitmq
  • 各服务构建流程（示例：gateway）：
    • make init → make api → make config → make ent → make generate → make build → make run

三、分支模型与提交规范

  • 分支
    • main 受保护；feature/、fix/、docs/用于日常开发；release/ 用于发版
  • 提交信息（Conventional Commits）
    • feat: 新功能
    • fix: 修复缺陷
    • docs: 文档变更
    • refactor: 重构（非功能/修复）
    • test: 测试相关
    • chore/build/ci: 工具链、构建、CI 变更
    • 示例：feat(agent): support workflow collection config CRUD

四、代码风格与静态检查

  • 必须通过 golangci-lint（项目已有 .golangci.yml）。本地执行：golangci-lint run
  • gofmt/goimports 无差异；go vet 必须通过
  • 建议开启 staticcheck（golangci-lint 集成）
  • 函数复杂度建议 ≤ 10；超过需拆分或在 PR 中说明理由
  • 命名约定：
    • 错误变量以 err 开头；布尔以 is/has/can 开头
    • 导出类型/函数需有注释；避免无意义缩写

五、测试规范与覆盖率门禁

  • 覆盖率要求
    • 全局最低：90%
    • 理想目标：95%+
    • 核心域（agent/point/distribution 等 usecase）：95%+
  • 测试类型
    • 单元测试：覆盖 biz/service 成功与错误路径
    • 集成测试：涉及 DB/缓存/队列的最小链路
    • 端到端：关键业务路径至少一条
  • Mock 策略
    • 使用数据库的服务：sqlmock + Ent；必须 mock.ExpectationsWereMet()
    • Gateway：使用“函数字段 mock”，不使用 gomock
  • 断言规范
    • 必须使用统一断言助手函数，验证返回对象所有字段（assert_<entity>Equal），禁止缺字段验证
  • 场景覆盖
    • 成功、参数缺失、依赖错误、NotFound、业务冲突、分页边界、可选参数分支（nil/true/false）
  • 命名规范
    • Test<Service><Method><Scenario>

六、API/IDL 与代码生成

  • 一律使用 protobuf 定义 gRPC/HTTP；HTTP 路由与字段行为注解齐全
  • 参数校验使用 protoc-gen-validate；新增字段需补充校验
  • 数组与复杂对象必须用 repeated 与 message，不得用 JSON 字符串
  • OpenAPI 文档：make swagger 生成 openapi.yaml；PR 必须包含更新
  • 兼容性：
    • 版本化（v1…）；禁止破坏性变更
    • 删除字段走弃用流程（deprecated，保留至少两个小版本）
  • 生成步骤（单服务）：
    • make init → make api → make config → make ent → make generate → make all

七、数据层与数据库规范（Ent/SQL）

  • ORM 统一使用 Ent；schema 变更后必须生成并提交
  • 事务使用 Ent Tx；禁止裸用 sql.Tx
  • 迁移：通过迁移文件/目录管理，禁止生产环境手工改表
  • 查询性能：
    • 大表/高频查询需索引；PR 说明索引策略
    • 复杂查询提供 explain 或性能说明
  • 多租户：
    • tenant_id 强隔离；Service 层必须校验租户上下文

八、消息队列与异步

  • 统一使用 pkg/mq/rabbitmq 封装
  • 消息结构需版本化，禁止破坏性变更
  • 消费者必须幂等；失败重试与死信策略需明确

九、安全与合规

  • 认证与授权：统一 JWT；S2S 使用短期 token
  • 输入校验：proto + service 双层校验（长度、范围、格式）
  • 日志脱敏：屏蔽密码、Token、支付信息等敏感字段
  • 依赖合规：禁止引入高危 CVE 版本；定期更新与扫描

十、可观测性与运维要求

  • 指标：暴露 Prometheus 指标（QPS、错误率、P95/P99 等关键业务指标）
  • 追踪：OpenTelemetry 贯通跨服务；传递 trace/tenant/user 上下文
  • 健康检查：提供 /health 与 gRPC 健康检查；依赖项检测
  • 日志：结构化 JSON；info/warn/error 合理分级

十一、PR 门禁与评审清单

  • 提交流程
    1. 本地生成代码并通过 verify（lint、fmt、vet、test、swagger）
    2. 提交 PR（净变更建议 < 800 行，过大请拆分）
  • 必过项（CI/审核）：
    • 编译通过，测试通过且覆盖率达标
    • golangci-lint、gofmt/goimports、go vet 通过
    • 生成代码与 OpenAPI 已更新（git diff 干净）
    • 安全：无明文 Secret；脱敏正确
    • 可观测性：关键路径日志/指标/追踪齐全
    • 数据库：索引/事务/锁与性能说明
    • 配置：Consul/Env 合法，具备回滚策略
  • Reviewer 清单：
    • 业务正确性与异常路径
    • 并发安全、超时、重试与熔断
    • 错误码与日志
    • 安全与脱敏
    • 指标与追踪
    • DB 查询与索引
    • 配置变更与回滚
    • 测试覆盖与断言完整性

十二、变更类型与发布

  • 变更类型：feat/fix/docs/refactor/test/chore/build/ci
  • 版本：语义化版本（MAJOR.MINOR.PATCH）
  • 发布：
    • 合并前：运行迁移/回滚验证
    • 部署：灰度放量；异常阈值触发回滚

附录：本地常用命令

  • 全仓工具初始化：make init（根）或进入服务目录执行
  • 生成 API/配置/Ent/DI：make api | make config | make ent | make generate | make all
  • 构建：make build；运行：make run（各服务）
  • Lint：golangci-lint run；格式化：gofmt -s -w . && goimports -w .
  • 测试：go test ./... -v -cover；生成覆盖率报告：go test ./... -coverprofile=coverage.out && go tool cover -html=coverage.out
  • OpenAPI：make swagger

如对规范有异议或需豁免，请在 PR 描述中明确说明并 @ 核心维护者评审。