364 lines
18 KiB
Markdown
364 lines
18 KiB
Markdown
# AGENTS.md
|
||
本文件用于指导 Codex (Codex.ai/code) 在此代码仓库中工作时的行为规范。
|
||
|
||
> 本规范适用于 BladeX 微服务平台的所有开发任务，为强制性条款。除非用户显式豁免，任何条目都不得忽视或删减。
|
||
>
|
||
> 作为 AI 助手参与本项目开发时，你必须：
|
||
> - 每次输出前深度理解 BladeX 微服务架构、Spring Cloud 全栈技术特征和多租户业务模型
|
||
> - 当回答依赖外部知识时，先查询 Spring Boot 3.x、Spring Cloud 2025、MyBatis-Plus 等官方文档
|
||
> - 若需求含糊，先复述已知信息并列出关键澄清问题
|
||
> - 面对复杂需求，先拆分为可管理的子任务
|
||
>
|
||
> 所有开发内容必须建立在深度思考过的基础之上，禁止机械生成与错误填充。
|
||
> 如果你已了解所有规范，请在用户第一次对话时说明："我已充分了解 BladeX 微服务平台开发规范。"
|
||
|
||
---
|
||
|
||
## 1. 项目概述
|
||
|
||
BladeX 是基于 Spring Cloud 2025 + Spring Boot 3.x 构建的**企业级微服务开发平台**，提供 SaaS 多租户、OAuth2 认证、数据/接口权限、工作流、分布式事务等核心能力。
|
||
|
||
---
|
||
|
||
## 2. 项目架构
|
||
|
||
```
|
||
BladeX/
|
||
├── blade-auth/ # OAuth2 认证授权服务
|
||
├── blade-common/ # 公共模块（常量、工具类、启动配置）
|
||
├── blade-gateway/ # Spring Cloud Gateway 网关服务
|
||
├── blade-ops/ # 运维服务模块
|
||
│ ├── blade-admin/ # Spring Boot Admin 监控
|
||
│ ├── blade-develop/ # 代码生成服务
|
||
│ ├── blade-flow/ # Flowable 工作流服务
|
||
│ ├── blade-job/ # 分布式任务调度
|
||
│ ├── blade-log/ # 日志服务
|
||
│ ├── blade-report/ # 报表服务
|
||
│ └── blade-resource/ # 资源管理服务（OSS、SMS）
|
||
├── blade-ops-api/ # 运维服务 API 契约
|
||
├── blade-plugin/ / blade-plugin-api/ # 插件扩展模块（预留）
|
||
├── blade-service/ # 业务服务模块
|
||
│ ├── blade-desk/ # 工作台服务（通知、流程）
|
||
│ └── blade-system/ # 系统管理服务（用户、角色、菜单、租户等）
|
||
├── blade-service-api/ # 业务服务 API 契约
|
||
├── doc/ # Nacos 配置 & 多数据库建表脚本
|
||
├── script/ # Docker / FatJar 部署脚本
|
||
└── pom.xml # Maven 父工程配置
|
||
```
|
||
|
||
### 2.1 分层架构
|
||
|
||
每个业务模块遵循标准分层，**API 与 Service 分离**：
|
||
|
||
| 层次 | 包路径 | 所在模块 |
|
||
| --- | --- | --- |
|
||
| Controller | `controller/` | Service 模块 |
|
||
| Service / ServiceImpl | `service/` + `service/impl/` | Service 模块 |
|
||
| Mapper（接口 + XML 同包） | `mapper/` | Service 模块 |
|
||
| Wrapper | `wrapper/` | Service 模块（Entity → VO 转换） |
|
||
| Entity / VO / DTO | `pojo/entity/` `pojo/vo/` `pojo/dto/` | **API 模块** |
|
||
| Feign Client | `feign/` | **API 模块**（含 Fallback 降级） |
|
||
| Cache | `cache/` | **API 模块** |
|
||
|
||
### 2.2 API 与 Service 分离原则
|
||
|
||
- **API 模块**（`blade-*-api`）：定义 Entity、VO、DTO、Feign 接口、Cache 工具，供其他服务依赖
|
||
- **Service 模块**（`blade-service/*`、`blade-ops/*`）：实现 Controller、ServiceImpl、Mapper、Wrapper
|
||
- 跨服务调用通过 Feign Client 完成，禁止直接依赖其他 Service 模块
|
||
|
||
> **与 Boot 版的关键区别**：Cloud 采用 API/Service 模块分离，跨服务通过 Feign 调用；Controller 路由无需 `AppConstant` 前缀（网关按服务名路由）。
|
||
|
||
---
|
||
|
||
## 3. 技术栈
|
||
|
||
| 类别 | 技术 |
|
||
| --- | --- |
|
||
| 基础框架 | Spring Boot 3.2.x / Spring Cloud 2025 / Maven |
|
||
| ORM | MyBatis-Plus（禁止 JDBC 直连） |
|
||
| 微服务 | Nacos（注册/配置）、Sentinel（熔断）、Seata（分布式事务）、OpenFeign |
|
||
| 网关 | Spring Cloud Gateway（WebFlux） |
|
||
| 安全 | OAuth2 / JWT（自研 Secure 框架）、数据权限、接口权限 |
|
||
| 缓存 | Redis（Protostuff 序列化） |
|
||
| 工作流 / 任务调度 | Flowable / PowerJob |
|
||
| 数据库连接池 | Druid |
|
||
| 文档 | Knife4j（OpenAPI 3.0） |
|
||
| 监控 | Spring Boot Admin / Prometheus / ELK / Zipkin |
|
||
| 数据库 | MySQL / PostgreSQL / Oracle / SQL Server / 达梦 / 人大金仓 / 崖山 |
|
||
|
||
---
|
||
|
||
## 4. 开发规范
|
||
|
||
### 4.1 编写新功能前
|
||
|
||
1. 先阅读目标模块中已有的类，理解其结构、命名和风格
|
||
2. 标准参考模块：`blade-service/blade-system`（Service）、`blade-service-api/blade-system-api`（API）
|
||
3. 主动模仿现有代码风格，包括缩进（Java 用 Tab，YAML/JSON 用 2 空格）、注解顺序、Javadoc 格式
|
||
4. 新建类必须包含 BladeX 商业许可证头部和 Javadoc 类注释（`@author Chill`）
|
||
|
||
### 4.2 编写完成后
|
||
|
||
1. 使用 `mvn clean compile -DskipTests` 编译验证，编译不通过必须修复
|
||
2. 引入模块依赖前先检查循环依赖，若存在则采用更优方案
|
||
3. 编译通过后将测试交由用户执行，**不得自行执行任何测试**
|
||
4. 除非用户明确要求，不应撰写示例或额外文档
|
||
|
||
### 4.3 代码生成
|
||
|
||
当需要生成 CRUD 全套代码（Entity、VO、Service、Controller、Wrapper、Mapper、建表语句等）时，优先使用 **`/blade-design`** skill。该 skill 可根据模块名、实体名和字段列表，自动生成符合 BladeX 框架规范的后端代码和多数据库建表语句，确保生成结果与项目风格完全一致。
|
||
|
||
---
|
||
|
||
## 5. 命名规范
|
||
|
||
### 5.1 包名
|
||
|
||
统一前缀 `org.springblade`，按模块划分：`system`、`desk`、`auth`、`gateway`、`develop`、`flow`、`common` 等
|
||
|
||
### 5.2 类名
|
||
|
||
| 类型 | 规则 | 示例 |
|
||
| --- | --- | --- |
|
||
| Entity | 直接类名 | `Notice`、`Tenant` |
|
||
| VO / DTO | `XxxVO` / `XxxDTO` | `NoticeVO`、`DeptDTO` |
|
||
| Service 接口 | `IXxxService` | `INoticeService` |
|
||
| Service 实现 | `XxxServiceImpl` | `NoticeServiceImpl` |
|
||
| Controller | `XxxController` | `NoticeController` |
|
||
| Mapper | `XxxMapper` | `NoticeMapper` |
|
||
| Wrapper | `XxxWrapper` | `NoticeWrapper` |
|
||
| Feign 接口 / 降级 | `IXxxClient` / `IXxxClientFallback` | `INoticeClient` |
|
||
| 表名 | `blade_` + 下划线 | `blade_notice` |
|
||
|
||
### 5.3 变量命名
|
||
|
||
- 必须具有明确语义：`Exception exception`（✅）`Exception e`（❌）；`List<Notice> noticeList`（✅）`List<Notice> list`（❌）
|
||
- 冲突时提升语义：`Cache cache; Cache noticeCache`（✅）`Cache cache1; Cache cache2`（❌）
|
||
|
||
---
|
||
|
||
## 6. 编码规范
|
||
|
||
### 6.1 注解顺序
|
||
|
||
- **Controller 类**：租户注解(`@TenantDS`/`@NonDS`) → `@RestController` → Lombok(`@AllArgsConstructor`) → 安全注解(`@PreAuth`) → `@RequestMapping` → `@Tag`
|
||
- **Controller 方法**：HTTP 方法注解 → `@ApiOperationSupport(order=N)` → `@Operation`
|
||
- **Entity 类**：`@Data` → `@EqualsAndHashCode` → `@TableName` → `@Schema`
|
||
- **VO 类**：`@Data` → `@EqualsAndHashCode(callSuper = true)` → `@Schema`
|
||
|
||
### 6.2 Entity-Service 继承体系（核心）
|
||
|
||
Entity 基类的选择**直接决定** Service 和 ServiceImpl 的继承方式，三者必须配套：
|
||
|
||
| 场景 | Entity | Service 接口 | ServiceImpl | 示例 |
|
||
| --- | --- | --- | --- | --- |
|
||
| **多租户业务表** | `extends TenantEntity` | `extends BaseService<T>` | `extends BaseServiceImpl<M, T>` | Notice, Post, Dept |
|
||
| **非租户业务表** | `extends BaseEntity` | `extends BaseService<T>` | `extends BaseServiceImpl<M, T>` | Tenant |
|
||
| **轻量级/关系表** | `implements Serializable` | `extends IService<T>` | `extends ServiceImpl<M, T>` | RoleMenu, Dict, Role |
|
||
|
||
- `TenantEntity` 继承自 `BaseEntity` 并额外包含 `tenantId`
|
||
- `BaseEntity` 包含：id, createUser, createDept, createTime, updateUser, updateTime, status, isDeleted
|
||
- `BaseService`/`BaseServiceImpl` 是 BladeX 增强版，提供 `deleteLogic()` 等方法，**要求 Entity 继承 BaseEntity 或 TenantEntity**
|
||
- `IService`/`ServiceImpl` 是 MyBatis-Plus 原生版，用于 `implements Serializable` 的轻量实体，删除用 `removeByIds()`
|
||
|
||
### 6.3 Controller 约定
|
||
|
||
- 继承 `BladeController`，使用 `@AllArgsConstructor` 注入
|
||
- **路由直接使用资源路径**（如 `@RequestMapping("notice")`），网关按服务名路由，无需 `AppConstant` 前缀（Boot 版需要前缀）
|
||
- 统一返回 `R<T>` 响应体
|
||
- Entity → VO 转换通过 `XxxWrapper.build().entityVO()` / `.pageVO()`
|
||
|
||
### 6.4 Feign Client（Cloud 特有）
|
||
|
||
- 定义在 API 模块的 `feign/` 包中
|
||
- `@FeignClient(value = AppConstant.APPLICATION_XXX_NAME)`
|
||
- 路径常量定义在接口内：`String API_PREFIX = "/feign/client/xxx"`
|
||
- 降级类命名：`IXxxClientFallback`
|
||
|
||
### 6.5 依赖注入
|
||
|
||
- Controller 使用 `@AllArgsConstructor` + `private final` 字段
|
||
- Service 需要额外依赖时使用 `@RequiredArgsConstructor` + `private final` 字段
|
||
|
||
### 6.6 Lombok
|
||
|
||
禁止手写 getter/setter，统一使用 `@Data`、`@EqualsAndHashCode(callSuper = true)`、`@AllArgsConstructor`、`@RequiredArgsConstructor`、`@Slf4j` 等
|
||
|
||
### 6.7 Java 17 特性
|
||
|
||
- 可使用增强 switch、Text Blocks、Pattern Matching for instanceof、`@Serial`
|
||
- **禁止** `var` / `val` 类型推断，所有变量显式声明类型
|
||
- 优先使用 Stream API，Lambda 保持简洁
|
||
|
||
### 6.8 MyBatis-Plus
|
||
|
||
- 简单查询使用 `LambdaQueryWrapper`，复杂查询写在 Mapper XML 中
|
||
- Mapper XML 与接口**同包**放置（`src/main/java` 下）
|
||
- 分页统一使用 `Condition.getPage(query)` + `Condition.getQueryWrapper()`
|
||
- 表格的排序默认按照创建时间降序；后端分页 SQL 或 QueryWrapper 应默认使用 `create_time DESC` / `orderByDesc(Xxx::getCreateTime)`，除非用户明确要求业务字段优先排序。
|
||
- 禁止 JDBC 直连查询
|
||
|
||
### 6.9 审计字段展示
|
||
|
||
- `create_user`、`update_user` 等审计字段只保存用户 ID，禁止为了展示姓名改变表结构或覆盖审计 ID。
|
||
- 面向前端的 VO 应额外提供 `createUserName`、`updateUserName` 等展示字段，并使用 `@TableField(exist = false)` 标记。
|
||
- Entity → VO 转换统一在 `XxxWrapper` 中完成；审计人姓名通过 `UserCache.getUserRealName(userId)` 获取，优先返回用户真实姓名，缓存未命中时兜底返回用户 ID。
|
||
- Controller 不应在列表、详情方法中重复编写审计人翻译逻辑，避免各模块显示规则不一致。
|
||
|
||
### 6.10 导出数据格式
|
||
|
||
- 导出 Excel、CSV 等文件时，金额类字段必须保留 2 位小数；即使原始数据为整数，也应导出为 `0.00` 形式。
|
||
- 导出经度、纬度字段时必须保留 6 位小数；导出前仍需遵守经度 `-180 ~ 180`、纬度 `-90 ~ 90` 的有效范围约束。
|
||
- 精度格式化应在导出 DTO/Excel 模型、导出组装逻辑或专用格式化工具中完成，禁止只依赖前端展示格式。
|
||
|
||
### 6.11 导入失败明细导出
|
||
|
||
- 所有 Excel 批量导入功能如果存在部分数据无法导入、校验失败或处理异常，后端必须将导入失败的数据导出为 Excel 文件返回给前端下载。
|
||
- 导入失败 Excel 的字段顺序必须与原导入模板保持一致，并在最后一列追加“导入失败原因”；失败原因应包含明确行号和可读错误信息。
|
||
- 导入模板本身不得包含失败原因列；如复用导入模型，应使用 `@ExcelIgnore` 忽略内部错误字段，或单独定义 `XxxImportFailureExcel` 模型。
|
||
- 导入逻辑应逐行处理：可成功导入的数据正常保存，失败行收集到失败明细；除非业务明确要求全量事务回滚，不得因部分失败回滚已成功行。
|
||
- Controller 在失败明细非空时应直接通过 `ExcelUtil.export` 写入 `HttpServletResponse`，文件名统一包含业务名称、`导入失败明细` 和时间戳；全部成功时返回标准 `R.success`。
|
||
- Service 层应返回失败明细列表或等效结构，禁止只抛出拼接后的错误字符串导致前端无法下载失败数据。
|
||
|
||
### 6.12 日志
|
||
|
||
- 使用 `@Slf4j`，占位符传参（禁止字符串拼接）
|
||
- 包含关键业务标识，异常必须携带堆栈，禁止打印敏感信息
|
||
|
||
---
|
||
|
||
## 7. 数据库规范
|
||
|
||
- **表名前缀**：`blade_`（如 `blade_notice`、`blade_user`）
|
||
- **业务表必含字段**：`id`(BIGINT)、`tenant_id`(VARCHAR)、`create_user`、`create_dept`、`create_time`、`update_user`、`update_time`、`status`、`is_deleted`
|
||
- **主键策略**：雪花算法（`IdType.ASSIGN_ID`），Long 字段用 `@JsonSerialize(using = ToStringSerializer.class)` 防精度丢失
|
||
- **逻辑删除**：`is_deleted` (INT)，0 = 未删除，1 = 已删除
|
||
- **索引命名**：唯一索引 `uk_` 前缀，普通索引 `idx_` 前缀
|
||
- **多数据库**：支持 7 种数据库，建表脚本位于 `doc/sql/`，修改表结构时需同步所有脚本
|
||
|
||
---
|
||
|
||
## 8. 多租户与安全
|
||
|
||
- **多租户**：默认字段隔离模式（`tenant_id`），MP 内置方法自动注入；自定义 SQL 需手动 `AuthUtil.getTenantId()`
|
||
- **租户注解**：`@TenantDS`（启用数据源切换）/ `@NonDS`（禁用切换）
|
||
- **权限注解**：`@PreAuth(menu = "xxx")`（菜单权限）、`@PreAuth(AuthConstant.PERMIT_ALL)`（公开）
|
||
- **数据权限**：DataScopeHandler 行级过滤
|
||
- **接口权限**：ApiScopeHandler 端点级控制
|
||
|
||
---
|
||
|
||
## 9. 缓存规范
|
||
|
||
- `CacheUtil` 统一操作，常量在 `CacheConstant`
|
||
- 数据变更后清除缓存：`CacheUtil.clear(CACHE_NAME, Boolean.FALSE)`
|
||
- 字典翻译：`DictCache.getValue(DictEnum.XXX, value)`
|
||
|
||
---
|
||
|
||
## 10. 商业许可头部
|
||
|
||
所有新建的 Java 源文件必须在文件顶部包含以下许可头部：
|
||
```java
|
||
/**
|
||
* BladeX Commercial License Agreement
|
||
* Copyright (c) 2018-2099, https://bladex.cn. All rights reserved.
|
||
* <p>
|
||
* Use of this software is governed by the Commercial License Agreement
|
||
* obtained after purchasing a license from BladeX.
|
||
* <p>
|
||
* 1. This software is for development use only under a valid license
|
||
* from BladeX.
|
||
* <p>
|
||
* 2. Redistribution of this software's source code to any third party
|
||
* without a commercial license is strictly prohibited.
|
||
* <p>
|
||
* 3. Licensees may copyright their own code but cannot use segments
|
||
* from this software for such purposes. Copyright of this software
|
||
* remains with BladeX.
|
||
* <p>
|
||
* Using this software signifies agreement to this License, and the software
|
||
* must not be used for illegal purposes.
|
||
* <p>
|
||
* THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY. The author is
|
||
* not liable for any claims arising from secondary or illegal development.
|
||
* <p>
|
||
* Author: Chill Zhuang (bladejava@qq.com)
|
||
*/
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 构建与部署
|
||
|
||
```bash
|
||
mvn clean compile -DskipTests # 编译验证
|
||
mvn clean package -DskipTests # 打包
|
||
mvn clean package docker:build -DskipTests # Docker 镜像
|
||
```
|
||
|
||
- Nacos 配置：`doc/nacos/blade-{dev|test|prod}.yaml`
|
||
- Docker 部署：`script/docker/app/docker-compose.yml`
|
||
- 开发环境默认：Nacos `localhost:8848`、Sentinel `localhost:8858`、Redis `127.0.0.1:6379`、MySQL `localhost:3306/bladex`
|
||
|
||
---
|
||
|
||
## 12. Git 提交规范
|
||
|
||
当需要提交代码时，优先使用 **`/blade-commit`** skill，它会自动分析变更内容并生成符合项目规范的 Gitmoji 提交信息。
|
||
|
||
采用 **Gitmoji** 风格，中文描述。格式：`:<gitmoji>: 简要描述`
|
||
|
||
| Gitmoji | 场景 | 示例 |
|
||
| --- | --- |------------------------|
|
||
| `:sparkles:` | 新增功能 | `:sparkles: 新增角色授权功能` |
|
||
| `:zap:` | 优化重构 | `:zap: 优化字典查询排序逻辑` |
|
||
| `:bug:` | 修复缺陷 | `:bug: 修复用户查询未过滤已删除数据` |
|
||
| `:tada:` | 版本发布 | `:tada: x.x.x.RELEASE` |
|
||
| `:recycle:` | 代码重构 | `:recycle: 重构租户删除逻辑` |
|
||
|
||
---
|
||
|
||
## 13. 框架组件速查
|
||
|
||
| 组件 | 用途 |
|
||
| --- | --- |
|
||
| `R<T>` | 统一 API 响应 |
|
||
| `BladeController` | Controller 基类 |
|
||
| `TenantEntity` / `BaseEntity` | 实体基类（多租户/非租户） |
|
||
| `BaseService` / `BaseServiceImpl` | BladeX 增强 Service（含 deleteLogic） |
|
||
| `BaseEntityWrapper` | Entity→VO 转换基类 |
|
||
| `BladeUser` | 当前登录用户（含租户信息） |
|
||
| `Condition` / `Query` | 查询条件构建 / 分页参数 |
|
||
| `CacheUtil` / `DictCache` | 缓存工具 / 字典缓存 |
|
||
| `AuthUtil` | 获取当前用户/租户信息 |
|
||
| `Func` / `BeanUtil` / `StringUtil` | 通用工具类 |
|
||
| `ServiceException` | 业务异常 |
|
||
| `@PreAuth` / `@TenantDS` / `@NonDS` | 权限 / 租户数据源切换 |
|
||
| `@BladeView` / `@DataRecord` / `@XssIgnore` | 视图控制 / 数据审计 / XSS 跳过 |
|
||
|
||
---
|
||
|
||
## 14. 风格一致性
|
||
|
||
1. 风格不确定时，优先查阅现有代码并模仿当前模块的实现方式
|
||
2. 新模块参考 `blade-service/blade-system` 作为标准模板
|
||
3. 现有模块已满足需求时，禁止自写替代实现
|
||
4. 与用户交互全程使用**中文**，代码注释和 Javadoc 亦使用中文
|
||
|
||
## 15. SQL生成要求
|
||
|
||
1.在生成表格的SQL文件时，需要同时生成菜单的插入SQL，以下为示例数据：
|
||
```mysql
|
||
id parent_id code name alias path source sort category action is_open component remark is_deleted
|
||
2075431169720033282 1164733399668962201 airport_master 空港机场主数据 airport_master /base/airport-master iconfont icon-fengche 30 1 0 1 0
|
||
2075431461312241665 2075431169720033282 airport_master_import 批量导入 airport_master_import 1 2 0 1 0
|
||
2075431522544885762 2075431169720033282 airport_master_template 下载模板 airport_master_template 1 2 0 1 0
|
||
2075431592346492929 2075431169720033282 airport_master_export 批量导出 airport_master_export 1 2 0 1 0
|
||
2075431635078062081 2075431169720033282 airport_master_delete 批量删除 airport_master_delete 1 2 0 1 0
|
||
2075431710063828994 2075431169720033282 airport_master_edit 编辑 airport_master_edit 1 2 0 1 0
|
||
2075431753298714626 2075431169720033282 airport_master_status 修改状态 airport_master_status 1 2 0 1 0
|
||
2075431820189474818 2075431169720033282 airport_master_add 新增 airport_master_add 1 2 0 1 0
|
||
```
|
||
2.生成的表、字段的排序规则要使用utf8mb4_general_ci
|