跳至主要內容

ADC 后端开发规范

2025/10/17大约 11 分钟

ADC 后端开发规范

目录

项目概述

微服务架构

本项目采用 Hyperf 微服务架构，各服务独立部署，通过 JSON-RPC 进行服务间通信。

技术栈

组件技术
框架Hyperf
服务通信JSON-RPC
数据库MySQL
消息队列RabbitMQ (AMQP)
服务注册Nacos
日志系统ELK Stack

开发环境规范

代码格式规范

⚠️ 强制规范：禁用编辑器保存时自动格式化！

多人协作时，编辑器自动格式化会导致合并冲突。请确保提交前统一使用以下命令格式化代码：

有 PHP 环境：

# 在项目根目录执行
vendor/bin/php-cs-fixer fix
# 或
composer cs-fix

无 PHP 环境（容器已启动）：

sh cs-fix.sh

公共基础包

位置： vendor/tgkw-adc/helper

更新拓展包：

composer update tgkw-adc/helper --ignore-platform-reqs

使用规范：

  • 请浏览该包内容，避免重复定义已有帮助函数
  • 业务代码全局日志记录统一使用 LogHelper
    • 位置：vendor/tgkw-adc/helper/src/Helper/Log/LogHelper.php

版本控制规范

Git 分支策略

分支类型命名规则用途
主分支main生产环境代码
开发分支dev开发环境代码
测试分支test测试环境代码
功能分支feature/{scope}-{short}新功能开发
修复分支hotfix/{issue}-{short}紧急问题修复

示例：

feature/user-login      # 用户登录功能
hotfix-payment-error    # 支付问题紧急修复

提交信息规范

格式： type(scope): summary

类型说明：

类型含义示例
feat新功能feat(user): 新增用户注册接口
fix修复 bugfix(api): 修复分页参数传递错误
docs文档变更docs(readme): 增加使用示例
refactor代码重构refactor(auth): 重构 JWT 鉴权逻辑
test测试相关test(login): 增加登录接口测试
chore构建/工具chore(deps): 升级依赖包到最新版本
perf性能优化perf(cache): 优化 Redis 查询性能
style代码格式style(lint): 调整代码缩进规则

提交示例：

feat(user): 新增用户注册接口
fix(api): 修复分页参数传递错误
docs(readme): 增加使用示例
refactor(auth): 重构 JWT 鉴权逻辑
perf(cache): 优化 Redis 查询性能

数据库规范

表结构管理

⚠️ 强制规范：禁止通过数据库工具直接创建或修改表结构！

统一使用框架的数据库迁移工具，每个表的新建或更新都必须有对应的迁移文件。

参考文档： https://hyperf.wiki/3.1/#/zh-cn/db/migration

表设计规范

维度规范示例
模型类名单数App\Model\Photo
类文件名单数app/Model/Photo.php
数据库表名复数 + Snake Casephotos、my_photos
迁移文件名单数 + 时间前缀2025_10_10_154417_create_photo_table.php
字段名Snake Caseview_count、is_vip
主键统一使用 idid
外键resource_id 格式user_id、post_id
时间字段bigint 存时间戳created_at、updated_at、deleted_at
操作人字段bigint 存用户 IDcreated_by、updated_by、deleted_by

索引设计原则

  1. 不建无用索引：避免为低频查询字段、全表扫描字段建索引
  2. 不重复建索引：如主键索引已包含 user_id，无需再为 user_id 建单字段索引
  3. 避免过度索引：单表索引数量建议不超过 5 个（索引越多，插入/更新维护成本越高）

API 开发规范

核心原则

  1. 接口风格：严格遵循 RESTful 设计，以「资源」为中心
  2. 数据格式：请求/响应体统一使用 application/json
  3. 版本控制：URL 路径中包含版本号（如 /v1/）
  4. 命名规范：
    • 路径：小写字母 + 复数形式 + kebab-case（如 user-groups）
    • 参数/字段：Snake Case（如 role_name、menu_ids）

RESTful 接口规范示例（角色管理）

HTTP 方法接口路径功能描述请求体要求
GET/v1/roles/columns获取列配置无（可通过 Query 参数筛选）
GET/v1/roles分页查询列表无（通过 Query 传分页/筛选条件）
GET/v1/roles/{id}获取单个详情无
POST/v1/roles新增角色必传完整信息
PUT/v1/roles/{id}全量更新必传完整字段
PATCH/v1/roles/{id}部分更新仅传需修改字段
PUT/v1/roles/{id}/menus修改菜单权限（覆盖）传菜单 ID 数组
POST/v1/roles/{id}/users新增成员传用户 ID 数组
DELETE/v1/roles/{id}/users移除成员传用户 ID 数组
DELETE/v1/roles/{id}删除单个无
DELETE/v1/roles/batch批量删除传 ID 数组

HTTP 方法语义

方法语义说明
GET查询仅查询资源，无副作用
POST创建创建新资源或增量添加关联
PUT全量更新替换完整资源，需传完整数据
PATCH部分更新仅修改部分字段
DELETE删除删除资源（支持单个/批量）

禁止示例（反模式）

❌ 错误示例问题说明✅ 正确写法
POST /v1/roles/update/{id}路径含动词 updatePUT /v1/roles/{id}
GET /v1/roles/delete?id=1用 GET 做删除操作DELETE /v1/roles/1
PUT /v1/roles（无 ID）全量更新未指定资源PUT /v1/roles/{id}
POST /v1/roleGroups/{id}/users多个单词用驼峰命名POST /v1/role-groups/{id}/users
DELETE /v1/roles?ids=1,2,3批量删除用 Query 参数DELETE /v1/roles/batch

路由规范

⚠️ 强制规范：必须使用注解路由

使用注解路由的原因：

  1. 开发更高效（减少切换文件）
  2. 可维护性好（代码即路由）
  3. 模块化友好（分布式路由）
  4. 文档自动化（Swagger 无缝集成）
  5. 启动自动注册（减少遗漏）

路由名称： 全小写，多个单词用中划线连接

请求验证规范

⚠️ 强制规范：必须使用验证 Request

规范要求：

  • 每个控制器对应一个 Request 类，继承 TgkwAdc\Request\BaseRequest
  • 不同方法使用不同场景（通过 @Scene 注解指定）
  • 控制器方法对应 Request 类中的不同场景

控制器规范

控制器职责：

职责说明
参数校验接收请求，触发 Request 场景校验
权限鉴权通过注解中间件进行权限和租户/机构隔离校验
协调编排将校验后的参数传递给 Service，不写业务逻辑
事务边界事务在 Service 层开启，控制器不直接管理事务
返回数据必须通过 Resource 封装，由 ApiResponseHelper 统一返回

服务层规范

位置： app/Service

规范要求：

维度规范
方法命名小驼峰格式（如 getUserList）
返回值单个对象返回具体类型或 null；集合返回数组或 Collection；分页返回 PaginatorInterface
业务验证在 Service 层进行业务规则验证，抛出有意义的异常
日志记录记录关键业务操作，包含必要的上下文信息
事务边界确保事务的原子性
避免 HTTP不直接处理 HTTP 请求，保持 Service 纯净性

异常示例：

throw new BusinessException(RoleCode::ROLE_NOT_EXIST);

资源类规范

⚠️ 强制规范：所有对外 API 必须通过 Resource 包装后返回！

详细内容请参考：ADC 后端 API 资源类使用指南

核心要求：

  • 所有资源类必须继承 TgkwAdc\Resource\BaseResource 或 TgkwAdc\Resource\BaseCollection
  • 通过 TgkwAdc\Helper\ApiResponseHelper 统一返回
  • Resource 只负责数据转换，不处理业务逻辑

目录结构：

app/Resource/
├── Application/    # 应用层资源类
│   └── V1/
│       ├── User/
│       │   ├── UserResource.php
│       │   └── UserCollection.php
└── Domain/         # 领域层资源类
    └── User/
        ├── UserResource.php
        └── UserCollection.php

错误码规范

⚠️ 强制规范：统一枚举化管理，禁止魔法数字

设计原则：

  • 分区分段：模块维度 + 业务细分
  • 统一枚举管理，支持国际化

编码规则（示例）：

类型错误码范围
成功0
通用错误1001xx
用户模块2001xx
订单模块3001xx

返回格式：

{
  "code": 1002001,
  "message": "用户不存在",
  "request_id": "a1b2c3d4",
  "data": null
}

使用示例：

return ApiResponseHelper::error(
    code: DemoCode::USER_STATUS_ERROR->getCode(),
    message: DemoCode::USER_STATUS_ERROR->genI18nMsg([
        'org_name' => '测试机构',
        'account_status' => '已通过',
    ])
);

MQ 命名规范

规范目标

  • 明确 Exchange/Queue 归属与用途，避免命名冲突
  • 支持跨服务消息投递与消费
  • 降低问题排查成本
  • 统一团队协作标准

核心命名规则

通用格式： [服务名].[功能模块].[操作/事件]

命名要求：

  • 仅允许字母（a-z/A-Z）、数字（0-9）、点（.）、连字符（-）
  • 采用「小驼峰 + 点分隔」风格
  • 服务名与 APP_NAME 环境变量保持一致（全小写）
  • 系统级标识以 system. 开头

Consumer 端规范（消息接收方）

Exchange 命名：

[服务名].[功能模块].[操作/事件]

示例：

  • 订单服务接收「订单创建」消息：order.order.createOrder
  • 系统级「全局通知」消息：system.notify.broadcast

Queue 命名：

[服务名].[功能模块].[操作/事件].queue

示例：

  • 订单服务队列：order.order.createOrder.queue
  • 系统级队列：system.notify.broadcast.queue

Producer 端规范（消息发送方）

Exchange 命名：

[目标服务名].[功能模块].[操作/事件]

示例：

  • 用户服务给订单服务发消息：order.order.createOrder（目标服务是 order）
  • 支付服务给系统发日志：system.log.paymentLog

跨服务通信示例

场景：A 服务（user）→ B 服务（order）发送「订单创建」消息

B 服务（Consumer）配置：

  • Exchange：order.order.createOrder
  • Queue：order.order.createOrder.queue
  • RoutingKey：order.createOrder

A 服务（Producer）配置：

  • Exchange：order.order.createOrder（目标服务的 Exchange）
  • RoutingKey：order.createOrder

接口规范

版本管理

⚠️ 强制规范：通过 URL 前缀进行版本化

  • 格式：/v1/、/v2/
  • 同一路由不同版本可并行维护
  • 废弃版本须在公告期后下线

请求响应格式

⚠️ 强制规范

维度规范
Content-Typeapplication/json; charset=utf-8
时间格式Y-m-d H:i:s（示例：2025-01-01 12:00:00）
数字精度涉及金额统一以最小货币单位存储，资源层格式化返回

分页排序规范

⚠️ 强制规范

入参：

  • current_page：当前页（默认 1）
  • per_page：每页数量（默认 10，最大 1000）
  • sort：排序字段
  • order：排序方向（asc/desc）

返回：

{
  "data": {
    "items": [],
    "total": 100,
    "current_page": 1,
    "per_page": 10,
    "last_page": 10
  }
}

幂等与限流

机制说明
幂等写操作支持 Idempotency-Key 请求头，同一 Key 在过期时间内返回相同结果
限流对敏感接口启用令牌桶/漏桶策略，超限返回标准错误码

追踪与日志

⚠️ 强制规范

维度规范
关联 ID请求头支持 X-Trace-Id，若无则服务端生成并在响应回写（基础中间件已处理）
必要审计登录、权限变更、资金/关键业务操作必须记录审计日志

统一错误响应格式：

{
  "code": 1001001,
  "message": "用户状态异常",
  "request_id": "a1b2c3d4",
  "data": []
}

常见问题

Q1：如何在开发中快速验证接口？

使用 apifox 进行接口测试。参考 adc-user 仓库的示例。

Q2：数据库迁移文件如何命名？

格式：{年}_{月}_{日}_{时间}_{操作}_{表名}.php

示例：2025_01_14_154417_create_user_table.php

Q3：跨服务调用使用什么协议？

统一使用 JSON-RPC 进行服务间通信。

Q4：如何处理接口版本兼容？

通过 URL 前缀区分版本（/v1/、/v2/），在资源类中做数据转换适配。

Q5：日志记录使用什么工具？

统一使用 LogHelper（位于 vendor/tgkw-adc/helper/src/Helper/Log/LogHelper.php）

附录

端口规划

注意： 以下端口为预留或已使用端口，请勿占用：

端口服务
5044Logstash Beats input
50000Logstash TCP input
9600Logstash monitoring API
9200Elasticsearch HTTP
9300Elasticsearch TCP transport
5601Kibana
9011ONLYOFFICE Document Server
8980ONLYOFFICE Document Server (HTTPS)
9000MinIO Console
9001MinIO API
5672RabbitMQ
15672RabbitMQ Management UI
8848Nacos
9848Nacos gRPC

微服务端口分配表

服务名称内部服务名根目录名HTTP 端口JSON-RPC 端口WebSocket
平台基础服务及系统后台publicadc-public96019701-
人事组织hradc-hr96029702-
用户服务useradc-user96039703-
日志服务logadc-log96049704-
审批服务approvaladc-approval960597059805
CRM系统crmadc-crm96069706-
任务中心taskadc-task960797079807
智慧工地ascadc-scs960897089808
消息中心messageadc-message960997099809
财务中心financeadc-finance96119711-
项目中心projectadc-project96129712-

参考文档

总结

本规范文档涵盖了 ADC 后端微服务项目的完整开发规范。所有标记为 ⚠️ 强制规范 的内容必须严格遵守，违反规范的代码将无法通过代码审查。

请团队成员在开发过程中严格按照本规范执行，确保代码质量和项目的可维护性。

最后更新： 2025-01-14

贡献者

ou.阳
最近更新: