init

2026-07-07 18:01:21 +08:00
commit b259f94d4b
1088 changed files with 121778 additions and 0 deletions
@@ -0,0 +1,444 @@
+# CLAUDE.md
+本文件用于指导 Claude Code (claude.ai/code) 在 BladeX-Tool 核心架构工程中工作时的行为规范。
+
+> 本规范适用于 BladeX-Tool 基础架构框架的所有开发任务，为强制性条款。除非用户显式豁免，任何条目都不得忽视或删减。
+>
+> 作为 AI 助手参与本项目开发时，你必须：
+> - 深刻理解本项目的定位：**核心架构工程**，为上层业务工程（BladeX-Boot / BladeX-Cloud）提供基础能力
+> - 每一行代码都可能被数百个下游项目引用，必须保证**向后兼容性**和**稳定性**
+> - 当回答依赖外部知识时，优先查询 Spring Boot 3.x、Spring Cloud 2025、MyBatis-Plus 等官方文档
+> - 引用外部资料须注明来源（链接或版本号）
+> - 若需求含糊，先复述已知信息并列出关键澄清问题
+> - 仅处理与问题直接相关的内容，避免冗余改动
+> - 面对复杂需求，先拆分为可管理的子任务
+>
+> 所有开发内容必须建立在深度思考过的基础之上，禁止机械生成与错误填充。
+> 如果你已了解所有规范，请在用户第一次对话时说明："我已充分了解 BladeX 微服务平台开发规范。"
+
+## 1. 工程定位与架构
+
+### 1.1 工程性质
+BladeX-Tool 是 BladeX 全栈微服务体系的**底层基础架构工程**，职责包括：
+- 提供通用工具类、基础实体、统一响应封装等核心能力
+- 封装 Spring Boot Starter 自动装配机制，实现开箱即用
+- 统一技术栈版本管理（BOM 物料清单）
+- 为安全认证、多租户、数据权限、分布式事务等横切关注点提供框架级支持
+
+**本工程不包含任何业务 CRUD 逻辑，所有代码均为框架级基础设施。**
+
+### 1.2 模块全景
+```
+BladeX-Tool/
+├── blade-bom/                          # BOM 物料清单，统一依赖版本管理
+├── blade-core-tool/                    # 核心工具库（100+ 工具类、API 响应封装、Jackson 配置）
+├── blade-core-boot/                    # Boot 单体应用基础配置（WebMvc、请求过滤、文件处理）
+├── blade-core-cloud/                   # Cloud 微服务基础配置（Feign、Sentinel、版本路由）
+├── blade-core-launch/                  # 应用启动器（属性加载、服务发现常量、启动监听）
+├── blade-core-context/                 # 线程上下文传递（Callable/Runnable 包装、Header 透传）
+├── blade-core-auto/                    # 编译期注解处理器（自动生成 spring.factories）
+├── blade-core-db/                      # 数据库基础配置
+├── blade-core-test/                    # 单元测试支持（BladeBootTest、BladeSpringExtension）
+├── blade-core-log4j2/                  # Log4j2 日志集成
+├── blade-core-auth/                    # 认证授权框架（聚合模块）
+│   ├── blade-core-oauth2/              #   OAuth2 认证实现（授权端点、令牌管理、异常处理）
+│   ├── blade-core-secure/              #   安全拦截框架（权限注解、拦截器、签名认证）
+│   ├── blade-starter-auth/             #   认证信息封装（AuthInfo、TokenInfo）
+│   ├── blade-starter-jwt/              #   JWT 令牌支持（生成、解析、Redis 存储）
+│   ├── blade-starter-key/              #   API Key 认证支持
+│   └── blade-starter-social/           #   第三方社交登录集成
+├── blade-starter-actuate/              # HTTP 响应缓存
+├── blade-starter-api-crypto/           # API 报文加解密（AES / DES / RSA）
+├── blade-starter-cache/                # 缓存管理工具
+├── blade-starter-data-record/          # 数据变更审计记录
+├── blade-starter-data-scope/           # 行级数据权限控制
+├── blade-starter-db-dynamic/           # 动态数据源路由
+├── blade-starter-develop/              # 代码生成器支持
+├── blade-starter-ehcache/              # EHCache 本地缓存
+├── blade-starter-excel/                # Excel 导入导出（FastExcel）
+├── blade-starter-flowable/             # Flowable 工作流引擎集成
+├── blade-starter-holidays/             # 节假日判定 API
+├── blade-starter-http/                 # HTTP 客户端封装（OkHttp3）
+├── blade-starter-i18n/                 # 国际化支持
+├── blade-starter-liteflow/             # LiteFlow 流程编排引擎
+├── blade-starter-literule/             # LiteRule 规则引擎
+├── blade-starter-loadbalancer/         # 负载均衡与灰度发布
+├── blade-starter-log/                  # 日志框架（请求日志、错误日志、ELK、链路追踪）
+├── blade-starter-metrics/              # 监控指标采集（Druid、Undertow、Sentinel）
+├── blade-starter-mongo/                # MongoDB 集成
+├── blade-starter-mybatis/              # MyBatis-Plus 集成（基础 Service / Mapper / Entity）
+├── blade-starter-mybatis-encrypt/      # 字段级透明加解密（AES / DES / SM4）
+├── blade-starter-oss/                  # 对象存储（Minio / 阿里云 / 腾讯云 / 七牛 / 华为云 / S3）
+├── blade-starter-powerjob/             # PowerJob 分布式任务调度
+├── blade-starter-prometheus/           # Prometheus 监控集成
+├── blade-starter-redis/                # Redis 全功能集成（缓存 / 分布式锁 / 限流 / 发布订阅 / Stream）
+├── blade-starter-report/               # UReport2 报表引擎
+├── blade-starter-sharding/             # ShardingSphere 分库分表
+├── blade-starter-sms/                  # 短信服务（阿里云 / 腾讯云 / 七牛 / 云片）
+├── blade-starter-swagger/              # Knife4j API 文档
+├── blade-starter-tenant/               # SaaS 多租户支持
+├── blade-starter-tenant-dynamic/       # 动态租户数据源路由
+├── blade-starter-trace/                # 分布式链路追踪
+├── blade-starter-transaction/          # Seata 分布式事务
+├── blade-starter-xss/                  # XSS 攻击防护
+└── pom.xml                             # Maven 父工程配置
+```
+
+### 1.3 核心理解要点
+1. **blade-core-auto 是编译期注解处理器**：通过 `@AutoService` 等注解在编译期自动生成 `META-INF/spring.factories` 和 `AutoConfiguration.imports`，无需手动维护
+2. **blade-bom 统一版本管理**：所有第三方依赖版本在此声明，下游工程通过 `<dependencyManagement>` 引入
+3. **blade-core-tool 是最底层模块**：几乎所有其他模块都依赖它，修改时需格外谨慎
+4. **blade-core-boot 与 blade-core-cloud 互斥**：分别用于单体应用和微服务应用，不可同时引入
+5. **Starter 模块遵循 Spring Boot 自动装配机制**：通过 `@AutoConfiguration` + `@ConditionalOnXxx` 实现按需加载
+
+## 2. 技术栈
+
+| 技术 | 版本 | 说明 |
+|------|------|------|
+| Java | 17 | 最低要求，可使用至 Java 17 的所有语法特性 |
+| Spring Framework | 6.2.15 | 核心框架 |
+| Spring Boot | 3.5.9 | 应用框架 |
+| Spring Cloud | 2025.0.1 | 微服务框架 |
+| Spring Cloud Alibaba | 2025.0.0.0 | 阿里云微服务组件 |
+| MyBatis-Plus | 3.5.14 | ORM 框架 |
+| Knife4j | 4.5.0 | API 文档（基于 OpenAPI 3） |
+| Jackson | 2.18.0 | JSON 序列化 |
+| OkHttp3 | 4.12.0 | HTTP 客户端 |
+| JJWT | 0.13.0 | JWT 令牌 |
+| Lombok | 1.18.42 | 代码简化 |
+| LiteFlow | 2.11.3 | 流程编排 |
+
+**构建工具**：Maven（使用 `flatten-maven-plugin` 管理 `${revision}` 版本号）
+
+## 3. 编码规范
+
+### 3.1 文件头部许可声明
+所有 Java 文件必须包含以下商业许可头部（位于 package 声明之前）：
+```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)
+ */
+```
+
+### 3.2 格式规范
+| 项目 | 规范 | 来源 |
+|------|------|------|
+| Java 缩进 | **Tab 字符**（非空格） | .editorconfig |
+| JSON/YAML 缩进 | 2 空格 | .editorconfig |
+| 文件编码 | UTF-8 | .editorconfig |
+| 换行符 | LF（Unix） | .editorconfig |
+| 尾部空白 | 自动去除 | .editorconfig |
+| 文件末尾 | 保留一个空行 | .editorconfig |
+| 行宽 | 建议不超过 120 字符 | 约定 |
+
+### 3.3 命名规范
+1. **包名**：统一前缀 `org.springblade.core.[模块名]`
+   - 示例：`org.springblade.core.mp.base`、`org.springblade.core.redis.cache`、`org.springblade.core.xss.processor`
+2. **类名**：
+   - 配置类：`XxxConfiguration` 或 `XxxAutoConfiguration`
+   - 属性类：`XxxProperties`（配合 `@ConfigurationProperties`）
+   - 工具类：`XxxUtil`（如 `WebUtil`、`StringUtil`、`SecureUtil`）
+   - 模板类：`XxxTemplate`（如 `OssTemplate`、`SmsTemplate`、`BladeRedis`）
+   - 拦截器：`XxxInterceptor`（如 `AuthInterceptor`、`XssInterceptor`）
+   - 处理器：`XxxHandler`（如 `BladeSecureHandler`、`TokenHandler`）
+   - 常量接口：`XxxConstant`（如 `BladeConstant`、`TokenConstant`）
+   - 基础实体：`BaseEntity`、`BizEntity`、`TenantEntity`
+   - 基础服务：`BaseService` / `BaseServiceImpl`、`BladeService` / `BladeServiceImpl`
+   - 注解：描述性命名（如 `@PreAuth`、`@DataAuth`、`@FieldEncrypt`、`@XssIgnore`）
+3. **变量与方法**：
+   - 必须具有明确语义，禁止无意义缩写
+   - ✅ `Exception chatProcessException`、`LambdaQueryWrapper<User> queryWrapper`
+   - ❌ `Exception e`、`LambdaQueryWrapper<User> w`
+   - 命名冲突时提升语义层级，禁止数字后缀（`cache1`、`cache2`）
+4. **常量**：`UPPER_SNAKE_CASE`，如 `CONTEXT_KEY`、`DB_PRIMARY_KEY`
+
+### 3.4 注解使用规范
+**类级别注解的推荐顺序**：
+```java
+@Slf4j                                // Lombok 日志
+@AutoConfiguration                    // Spring Boot 3 自动配置（取代 @Configuration）
+@RequiredArgsConstructor              // Lombok 构造器注入
+@EnableConfigurationProperties(XxxProperties.class)
+@ConditionalOnProperty(...)           // 条件装配
+@ConditionalOnWebApplication(type = Type.SERVLET)
+public class XxxConfiguration {
+```
+
+**字段级别注解的推荐顺序（实体类）**：
+```java
+@JsonSerialize(using = ToStringSerializer.class)  // 序列化
+@Schema(description = "主键id")                     // OpenAPI 文档
+@TableId(value = "id", type = IdType.ASSIGN_ID)    // MyBatis-Plus
+@BladeView(Views.Admin.class)                       // 视图控制
+private Long id;
+```
+
+### 3.5 Lombok 规范
+- 使用 `@Data` 替代手写 getter/setter
+- 使用 `@RequiredArgsConstructor` 配合 `final` 字段实现构造器注入，优先于 `@Autowired`
+- 使用 `@Slf4j` 注入日志对象
+- 实体类使用 `@Data`，配置类使用 `@RequiredArgsConstructor` 或 `@AllArgsConstructor`
+
+### 3.6 Java 语言特性
+1. 基于 Java 17，可使用以下特性：
+   - 增强 switch 表达式（Java 12+）
+   - Text Blocks 文本块（Java 13+）
+   - Pattern Matching for instanceof（Java 16+）
+   - Sealed Classes 密封类（Java 17）
+   - Records 记录类（Java 16+，视场景使用）
+2. **禁止使用 `var` / `val`**，所有变量必须显式声明类型
+3. 数据处理优先使用 Stream API，避免传统 for 循环
+4. Lambda 保持简洁：
+   - ✅ `() -> "something"`、`list.forEach(Template::shutdown)`
+   - ❌ `(x) -> { doSomething(x); }`、`() -> { return "something"; }`
+
+### 3.7 Import 规范
+- 禁止使用通配符导入（`import xxx.*`）
+- 导入分组顺序（组间空行分隔）：
+  1. `jakarta.*` / `javax.*`
+  2. 第三方库（`com.*`、`io.*`、`net.*`）
+  3. `org.springframework.*`
+  4. `org.springblade.*`
+  5. `java.*`
+
+### 3.8 Javadoc 规范
+```java
+/**
+ * 统一API响应结果封装
+ *
+ * @author Chill
+ */
+```
+- 类注释：简洁的一行中文描述 + `@author` 标签
+- 方法注释：中文描述 + `@param` + `@return`（工具方法可用英文）
+- 字段注释：使用 `/** */` 单行 Javadoc
+- 不写显而易见的注释，不添加 `@since`、`@version` 等冗余标签
+
+## 4. 框架开发规范
+
+### 4.1 自动装配模块开发模式
+创建新的 Starter 模块时，遵循以下结构：
+```
+blade-starter-xxx/
+├── src/main/java/org/springblade/core/xxx/
+│   ├── config/           # 自动配置类（@AutoConfiguration）
+│   ├── props/            # 配置属性类（@ConfigurationProperties）
+│   ├── annotation/       # 自定义注解
+│   ├── aspect/           # AOP 切面
+│   ├── interceptor/      # 拦截器
+│   ├── handler/          # 处理器接口与默认实现
+│   ├── constant/         # 常量定义
+│   ├── exception/        # 异常定义
+│   └── utils/            # 工具类
+└── pom.xml
+```
+
+**关键要求**：
+- 配置类使用 `@AutoConfiguration`（Spring Boot 3 规范，取代 `@Configuration`）
+- 必须配合 `@ConditionalOnXxx` 注解实现条件装配，避免强制加载
+- 提供 `@ConditionalOnMissingBean` 允许下游覆盖默认实现
+- 属性类使用 `@ConfigurationProperties` 并提供合理默认值
+- 通过 `blade-core-auto` 注解处理器自动生成 `spring.factories`，无需手动维护
+
+### 4.2 自动配置类示例
+```java
+@Slf4j
+@AutoConfiguration
+@RequiredArgsConstructor
+@EnableConfigurationProperties(XxxProperties.class)
+@ConditionalOnProperty(value = "blade.xxx.enabled", havingValue = "true", matchIfMissing = true)
+public class XxxConfiguration {
+
+	@Bean
+	@ConditionalOnMissingBean
+	public XxxTemplate xxxTemplate(XxxProperties properties) {
+		return new XxxTemplate(properties);
+	}
+
+}
+```
+
+### 4.3 工具类开发规范
+```java
+/**
+ * Xxx工具类
+ *
+ * @author Chill
+ */
+public class XxxUtil {
+
+	/**
+	 * 工具方法说明
+	 *
+	 * @param param 参数说明
+	 * @return 返回值说明
+	 */
+	public static String doSomething(@Nullable String param) {
+		// 实现逻辑
+	}
+
+}
+```
+- 工具类通常为 `final class` 或含静态方法的普通类
+- 可继承 Spring 已有工具类进行扩展（如 `WebUtil extends org.springframework.web.util.WebUtils`）
+- 参数使用 `@Nullable` 标注可空性
+- 优先复用 `blade-core-tool` 中已有的工具方法，禁止重复造轮子
+
+### 4.4 常量定义规范
+```java
+/**
+ * 系统常量
+ *
+ * @author Chill
+ */
+public interface BladeConstant {
+
+	String UTF_8 = "UTF-8";
+
+	String CONTEXT_KEY = "bladeContext";
+
+	String DB_PRIMARY_KEY = "id";
+
+}
+```
+- 使用 `interface` 定义常量（非 `class` + `static final`），便于直接 `implements` 引用
+- 按业务领域分组到不同的常量接口
+
+### 4.5 向后兼容性要求
+作为核心架构工程，以下变更属于 **Breaking Change**，须特别谨慎：
+- 删除或重命名 public 类、方法、字段
+- 变更方法签名（参数类型、返回类型、异常声明）
+- 修改配置属性 key（`blade.xxx.yyy`）
+- 变更 Bean 名称或条件装配逻辑
+- 升级依赖的 major 版本
+
+若必须进行 Breaking Change，需在 commit message 中明确标注影响范围。
+
+## 5. 日志规范
+
+### 5.1 基本要求
+- 使用 Lombok `@Slf4j` 注入日志对象
+- 使用占位符 `{}` 而非字符串拼接
+- 包含关键业务标识（如 tenantId、userId、requestId 等）
+- 异常日志必须包含堆栈信息（异常对象作为最后一个参数）
+- 禁止打印敏感信息（API Key、密码、令牌等）
+
+### 5.2 示例
+```java
+@Slf4j
+public class TokenGranterFactory {
+
+	public TokenGranter getGranter(String grantType) {
+		TokenGranter granter = granterMap.get(grantType);
+		if (granter == null) {
+			log.error("不支持的授权类型: grantType={}", grantType);
+			throw new GranterInvalidException("不支持的授权类型");
+		}
+		log.info("获取令牌授权器: grantType={}, granterClass={}", grantType, granter.getClass().getSimpleName());
+		return granter;
+	}
+
+}
+```
+
+## 6. 编译与验证
+
+### 6.1 开发完成后必须执行
+```bash
+mvn clean compile -DskipTests
+```
+
+### 6.2 编译规则
+1. 编译出现错误必须修复后重新编译，直至通过
+2. 引入模块间依赖前，必须检查是否会造成**循环依赖**
+3. 若存在循环依赖风险，采用接口抽象、事件机制等方式规避
+4. 编译通过后，将完整测试流程交由用户执行，由用户反馈日志进行进一步调整
+5. **不得自行执行任何集成测试或启动应用**
+6. 除非用户明确要求，不撰写示例代码或额外文档
+
+## 7. 自主学习与风格一致性
+
+1. **模仿优先**：遇到风格不确定的场景，优先查阅同模块现有代码并模仿
+2. **查找复用**：编写新功能前，先在 `blade-core-tool` 和相关 Starter 中搜索是否已有可复用的类或方法
+3. **禁止替代**：若现有模块已满足需求，禁止自写替代实现
+4. **标记不确定性**：确认已学习现有代码后仍不确定的，使用 `// TODO: 确认命名规范` 标记并告知用户
+5. **最小改动原则**：修改核心模块时，改动范围必须最小化，避免影响无关功能
+
+## 8. Git 提交规范
+
+### 8.1 提交格式
+本项目使用 **Gitmoji** 风格，与现有提交历史保持一致：
+```
+:gitmoji: 简要描述（中文）
+```
+
+### 8.2 常用 Gitmoji
+| Emoji | Code | 场景 |
+|-------|------|------|
+| :sparkles: | `:sparkles:` | 新增功能 / 新增类 |
+| :zap: | `:zap:` | 性能优化 / 逻辑优化 |
+| :bug: | `:bug:` | 修复 Bug |
+| :recycle: | `:recycle:` | 重构代码 |
+| :memo: | `:memo:` | 文档变更 |
+| :art: | `:art:` | 代码格式化 / 结构调整 |
+| :tada: | `:tada:` | 版本发布 |
+| :fire: | `:fire:` | 删除代码或文件 |
+| :lock: | `:lock:` | 安全相关修复 |
+| :arrow_up: | `:arrow_up:` | 升级依赖版本 |
+| :wrench: | `:wrench:` | 配置文件变更 |
+| :white_check_mark: | `:white_check_mark:` | 测试相关 |
+
+### 8.3 示例
+```
+:sparkles: 新增BladeView视图序列化机制，支持按角色动态控制JSON输出字段
+:zap: 优化动态数据源加载驱动类逻辑
+:bug: 修复多租户场景下缓存隔离失效问题
+:arrow_up: 升级Spring Boot至3.5.9
+```
+
+## 9. 单元测试规范
+```java
+@ExtendWith(BladeSpringExtension.class)
+@BladeBootTest(appName = "blade-test", enableLoader = true)
+public class XxxTest {
+
+	@Autowired
+	private XxxService xxxService;
+
+	@Test
+	public void testXxx() {
+		// 测试逻辑
+	}
+
+}
+```
+- 测试类使用 `blade-core-test` 提供的 `@BladeBootTest` 注解
+- 测试方法名必须具有描述性
+
+## 10. 交互规范
+
+1. 与用户交互时全程使用**中文**
+2. 若用户指定切换语言则遵从，否则始终保持中文
+3. 代码注释、Javadoc 使用中文（工具类方法可用英文）
+4. commit message 使用中文描述