107 lines
10 KiB
Markdown
107 lines
10 KiB
Markdown
# `biz-api-cloud-zax` 开发规则
|
||
|
||
> 适用于 Java 后端多模块项目。执行任务前必须先完整阅读 [HQ Platform 通用规则](../agents/common.md)，并继续检查目标模块内更具体的说明和现有同类实现。
|
||
|
||
## 技术栈基线
|
||
|
||
以下为当前父 POM 和 BOM 的扫描结果。实际版本以根 `pom.xml` 与 `pjcloud-common/pjcloud-common-bom/pom.xml` 为准，禁止在子模块中随意覆盖统一版本。
|
||
|
||
- 工程版本：`com.bsd:pjcloud:5.7.0`，Maven 多模块工程。
|
||
- 运行环境：Java 17、Spring Boot `3.3.6`、Spring Cloud `2023.0.4`、Spring Cloud Alibaba `2023.0.3.2`。
|
||
- 服务治理：Nacos 注册发现与配置中心、Spring Cloud Gateway、OpenFeign、Feign OkHttp、Spring Cloud LoadBalancer、Sentinel、Caffeine。
|
||
- 安全认证：Spring Security、OAuth2/Jose、Spring Authorization Server `1.4.0`，项目内统一安全组件与方法级 `@PreAuthorize` 权限校验。
|
||
- 数据访问：MyBatis-Plus `3.5.9`、MyBatis-Plus Join `1.5.2`、动态数据源 `4.3.1`、Druid `1.2.23`、MySQL Connector/J `8.3.0`。
|
||
- 缓存：Spring Data Redis；网关还使用 Reactive Redis。缓存访问应通过项目公共组件和既有模板，不自行创建不一致的序列化方案。
|
||
- 分布式事务：Seata `1.7.0`，由 `pjcloud-common-seata` 统一封装。
|
||
- 接口与文档：Spring MVC / WebFlux、Springdoc OpenAPI `2.1.0`、Knife4j；统一响应通常使用项目 `R<T>`。
|
||
- 服务容器与构建：业务 Web 服务普遍使用 Undertow，Maven Spring Boot 插件负责打包，Fabric8 Docker Maven Plugin 提供镜像构建能力。
|
||
- 流程与任务：Flowable `7.0.0`、XXL-Job、Quartz、ElasticJob 相关模块。
|
||
- 消息与实时能力：Spring Integration MQTT、WebSocket、SSE。
|
||
- 公共业务能力：OSS、Excel、日志、审计、幂等、接口加解密、数据脱敏、XSS 过滤、分布式序列、灰度路由、数据权限等均已有公共模块。
|
||
- 常用基础库：Lombok、Hutool、Jasypt 等。是否可用仍需看目标模块 POM，不能因为 BOM 管理了版本就直接在任意模块引用。
|
||
|
||
## 顶层服务与模块职责
|
||
|
||
- `pjcloud-register`：内置 Nacos 注册/配置中心相关模块。
|
||
- `pjcloud-gateway`：Spring Cloud Gateway 网关，负责动态路由、Reactive Redis、Sentinel 网关限流和聚合接口文档等。
|
||
- `pjcloud-auth`：OAuth2 认证授权中心，依赖统一安全、Feign、Redis、验证码和灰度路由能力。
|
||
- `pjcloud-upms`：用户、部门、角色、菜单、租户、字典等基础权限管理，拆分为 `api` 与 `biz`。
|
||
- `pjcloud-app-server`：移动端应用配置、页面、TabBar 及 App 侧公共服务，拆分为 `api` 与 `biz`。
|
||
- `pjcloud-canteen`：食堂、菜品、库存、预订、配送等业务，拆分为 `api` 与 `biz`。
|
||
- `pjcloud-hardware`：门禁、设备、硬件商品/订单等能力，拆分为 `api` 与 `biz`。
|
||
- `pjcloud-integrated`：访客、会议、反馈、公告、车辆、广告等综合业务，拆分为 `api` 与 `biz`。
|
||
- `pjcloud-wallet`：钱包、充值、交易、商户结算等业务，拆分为 `api` 与 `biz`。
|
||
- `pjcloud-supermarket`：商城、商品、SKU、库存和 ERP 等业务，拆分为 `api` 与 `biz`。
|
||
- `pjcloud-thirdparty`：第三方认证、支付、门禁和外部系统集成，拆分为 `api` 与 `biz`。
|
||
- `pjcloud-mqtt`：MQTT 接入与消息能力，拆分为 `api` 与 `biz`。
|
||
- `pjcloud-pass`：通行相关业务，拆分为 `api` 与 `biz`。
|
||
- `pjcloud-flow`：流程引擎与流程任务，内部继续拆分 engine/task 的 `api` 和 `biz`。
|
||
- `pjcloud-visual`：代码生成、报表、监控、微信/支付平台、Quartz、ElasticJob、XXL-Job 管理端等辅助服务。
|
||
- `pjcloud-boot`：聚合多个业务模块的单体启动方式；修改公共业务时需同时考虑微服务模式和 Boot 聚合模式。
|
||
|
||
## `api` / `biz` 分层规则
|
||
|
||
- 典型业务模块使用父聚合模块 + `*-api` + `*-biz` 结构。
|
||
- `*-api` 放跨模块契约：Feign Client、DTO、VO、Entity、常量及必要接口。不得把 Controller、具体 Service 实现或仅本服务内部使用的实现细节放入 API 模块。
|
||
- `*-biz` 放运行实现：启动类、Controller、Service/Impl、Mapper、配置、任务和资源文件。
|
||
- 跨服务只能依赖对方 `*-api` 和 Feign 契约，不得直接依赖对方 `*-biz`、Mapper 或 ServiceImpl。
|
||
- 新增类型前先搜索现有 DTO、VO、Entity 和公共 `R<T>`；请求对象、响应对象、持久化对象职责要分开，不用 Map 或 Entity 随意穿透所有层。
|
||
- Controller 负责参数接收、权限和响应包装，复杂业务放 Service；Mapper 负责数据访问，不在 Controller 堆叠查询与事务逻辑。
|
||
|
||
## 数据、缓存、事务与远程调用
|
||
|
||
- 持久化沿用 MyBatis-Plus、项目 `PjcloudBaseMapper`、现有分页 `Page`、Wrapper 与 XML/Mapper 风格。使用 MP Join 或自定义 SQL 前先看同模块已有写法。
|
||
- 多租户、数据权限和审计逻辑可能由公共 Mapper、拦截器或上下文提供。禁止用手写 SQL 绕过租户/数据范围约束。
|
||
- **不得修改数据库字段和表结构。** 需求缺少字段时先使用现有模型评估替代方案；确实必须调整时停止实现并请求用户明确授权。
|
||
- 事务方法应放在 Spring 管理的 Service 层，明确 `rollbackFor`；跨库/跨服务一致性需要评估本地事务、Seata、补偿和幂等，不能把一次远程调用误认为本地事务的一部分。
|
||
- Redis 必须复用已有 Key、序列化、Template/工具类和过期策略。修改数据库数据时同步评估缓存更新或失效；不要新增永久缓存或无命名空间 Key。
|
||
- Redis 基础设施会根据当前租户上下文自动处理租户 Key 前缀；使用 `RedisTemplate`、`StringRedisTemplate`、Redisson 锁及其他 Redis 对象时，业务代码只声明稳定的业务 Key，禁止读取或拼接 `TenantContextHolder.getTenantId()` 等租户编号。跨租户任务应通过 `TenantBroker` 等既有能力切换租户上下文；确需全局共享的 Key 必须沿用项目已有全局 Key 契约，不得用手工拼接方式绕过隔离。
|
||
- 远程调用通过已有 Feign Client，复用统一请求头、内部调用标识、LoadBalancer、Sentinel 降级和异常约定。禁止在业务代码中手写服务地址进行 HTTP 调用。
|
||
- Feign 返回 `R<T>` 时必须检查业务状态与空数据；不得只判断 HTTP 成功。
|
||
- 接口加解密已有 `pjcloud-common-encrypt-api`，前端也已有对应拦截器。不得在单个接口另造不兼容的加密协议。
|
||
|
||
## 配置、安全与接口约定
|
||
|
||
- 各服务 `application.yml` 通常只保存启动端口、服务名和 Nacos 引导配置，并导入 `application-{profile}.yml` 与服务级配置。修改配置前同时检查本地文件、环境变量占位符和 Nacos 配置来源。
|
||
- 不得把账号、密码、密钥、Token、证书或生产地址硬编码进仓库。发现现有敏感配置也不得在无关任务中扩散或复制。
|
||
- 方法权限遵循现有 `@PreAuthorize("@pms.hasPermission('...')")` 风格，权限字符串需与管理端菜单/按钮权限对应。
|
||
- 认证、Token、租户头、内部调用头和数据权限由公共安全组件处理；新增公开接口、匿名接口或内部接口必须先核对现有注解和安全白名单机制。
|
||
- 接口路径、HTTP 方法、分页参数、统一返回码、异常处理和 OpenAPI 注解跟随同 Controller 的现有风格。
|
||
- 删除或改变已有字段、枚举值、接口路径和返回结构前必须评估 PC、App 与其他服务调用方；默认保持向后兼容。
|
||
|
||
## 公共模块复用指引
|
||
|
||
- 核心工具与返回结构：`pjcloud-common-core`。
|
||
- 数据与 MyBatis 扩展：`pjcloud-common-data`、`pjcloud-common-datasource`。
|
||
- 认证授权：`pjcloud-common-security`。
|
||
- 远程调用：`pjcloud-common-feign`。
|
||
- 限流降级与分布式事务：`pjcloud-common-sentinel`、`pjcloud-common-seata`。
|
||
- 文档与网关：`pjcloud-common-swagger`、`pjcloud-common-gateway`。
|
||
- 日志、审计、幂等：`pjcloud-common-log`、`pjcloud-common-audit`、`pjcloud-common-idempotent`。
|
||
- 文件、Excel、任务：`pjcloud-common-oss`、`pjcloud-common-excel`、`pjcloud-common-job`。
|
||
- 实时通信：`pjcloud-common-websocket`、`pjcloud-common-sse`。
|
||
- 安全辅助：`pjcloud-common-encrypt-api`、`pjcloud-common-sensitive`、`pjcloud-common-xss`。
|
||
- 其他基础设施：`pjcloud-common-gray`、`pjcloud-common-sequence`。新增通用能力前先确认这里是否已有实现。
|
||
|
||
## 常用命令与验证
|
||
|
||
- 在后端根目录按模块验证：`mvn -pl <模块路径> -am test`。
|
||
- 仅需编译/打包时：`mvn -pl <模块路径> -am -DskipTests package`，但不能用跳过测试的结果冒充测试通过。
|
||
- 修改 `*-api`、公共模块或 BOM 时，应验证所有直接依赖模块，必要时执行更大范围构建。
|
||
- 修改网关、安全、数据、Feign、缓存、加解密或 Boot 聚合模块时，属于高影响改动，必须扩大测试范围并检查微服务与单体两种启动关系。
|
||
- 当前自动化测试分布不均。集中验证时，无现成测试的模块也应完成针对性编译，并对关键业务补充与现有测试风格一致的测试。
|
||
|
||
## 开发规则
|
||
|
||
- 修改前先确认所属业务模块及其 `api` / `biz` 边界，沿用现有 Controller、Service、Mapper、DTO、VO、Feign Client、异常处理、鉴权和统一响应结构。
|
||
- 跨服务调用优先遵循项目现有 OpenFeign 封装、服务名、请求模型、降级与异常处理方式，不得绕过已有边界直接耦合其他服务内部实现。
|
||
- Redis 使用必须复用已有缓存工具、序列化方式、键命名规则和过期策略。新增或修改缓存逻辑时，必须考虑缓存穿透、数据一致性、失效时机和空值处理。
|
||
- MySQL 持久化必须沿用已有 Mapper/ORM、事务和分页方式。未经用户明确同意，不得以任何形式修改数据库结构。
|
||
- 关键业务方法、事务边界、缓存一致性处理、远程调用容错和复杂查询必须添加必要的中文注释。
|
||
- 接口变更必须评估后台管理端、移动端及其他服务调用方的兼容性；优先保持向后兼容。
|
||
- 日常修改不自动运行 Maven 测试、编译或打包；收到用户明确的集中验证指令后，再验证受影响模块，多模块依赖变更同时验证直接依赖模块。
|
||
|
||
## 完成前项目检查
|
||
|
||
- [ ] 后端改动已考虑接口兼容、事务、缓存和远程调用影响。
|