11 KiB
11 KiB
biz-api-cloud-zax 开发规则
适用于 Java 后端多模块项目。执行任务前必须先完整阅读 HQ Platform 通用规则，并继续检查目标模块内更具体的说明和现有同类实现。
技术栈基线
以下为当前父 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 Cloud2023.0.4、Spring Cloud Alibaba2023.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 Join1.5.2、动态数据源4.3.1、Druid1.2.23、MySQL Connector/J8.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，前端也已有对应拦截器。不得在单个接口另造不兼容的加密协议。
数据库迁移交付规则
- 用户授权数据库调整后，必须在本项目
db/下新建独立的YYYYMMDD_变更说明.sql迁移文件，不能仅修改历史迁移或初始化 SQL。 - 迁移保持简单、可重复执行；新增表或列时先检查是否存在，避免重复执行报错，不混入无关业务数据改写。
- 编写迁移不代表获准执行；未经用户额外授权，不得对现有环境数据库执行脚本。
配置、安全与接口约定
- 各服务
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 聚合模块时，属于高影响改动，必须扩大测试范围并检查微服务与单体两种启动关系。
- 当前自动化测试分布不均。集中验证时，无现成测试的模块也应完成针对性编译，并对关键业务补充与现有测试风格一致的测试。
开发规则
- 新增源码文件不写版权/许可注释头（
Copyright (c) pjcloud开头的大段/* */块）。既有文件里的此类注释头保持原样，不主动清理、不扩散到新文件。 - 修改前先确认所属业务模块及其
api/biz边界，沿用现有 Controller、Service、Mapper、DTO、VO、Feign Client、异常处理、鉴权和统一响应结构。 - 跨服务调用优先遵循项目现有 OpenFeign 封装、服务名、请求模型、降级与异常处理方式，不得绕过已有边界直接耦合其他服务内部实现。
- Redis 使用必须复用已有缓存工具、序列化方式、键命名规则和过期策略。新增或修改缓存逻辑时，必须考虑缓存穿透、数据一致性、失效时机和空值处理。
- MySQL 持久化必须沿用已有 Mapper/ORM、事务和分页方式。未经用户明确同意，不得以任何形式修改数据库结构。
- 关键业务方法、事务边界、缓存一致性处理、远程调用容错和复杂查询必须添加必要的中文注释。
- 接口变更必须评估后台管理端、移动端及其他服务调用方的兼容性；优先保持向后兼容。
- 日常修改不自动运行 Maven 测试、编译或打包；收到用户明确的集中验证指令后，再验证受影响模块，多模块依赖变更同时验证直接依赖模块。
完成前项目检查
- 后端改动已考虑接口兼容、事务、缓存和远程调用影响。