# 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 使用中文描述