Claude.md for Java

1. 项目概览

定位：[一句话描述项目核心价值和目标用户]
规模：[开发团队规模] 人，[预期用户数]，内部/外部使用，[部署方式]
技术栈：如 Spring Boot + MyBatis-Plus + Vue + MySQL 8.x + Redis + pgvector
架构模式：如模块化单体（Modular Monolith），代码边界清晰，可平滑拆分为微服务

2. 核心功能模块（MVP）

模块	说明	核心职责
`[module_a]`	[简短描述]	[主要功能点]
`[module_b]`	[简短描述]	[主要功能点]

如

模块	说明
模型管理 (model)	管理 OpenAI / Claude / Gemini / Ollama 等 LLM 提供商配置，支持连通性测试
Agent 配置 (agent)	配置 Agent 名称、系统提示词、绑定模型、关联知识库和 MCP 工具
...

暂不纳入的功能（后续迭代）：如多租户、自定义插件市场、实时协作、企业 SSO、精细化权限控制、数据集版本管理。

3. 代码组织规范

3.1 包结构

▼
yaml
复制代码
com.[project]
├── common/
│   ├── config/          # 全局配置 (MybatisPlusConfig, ThreadPoolConfig 等)
│   ├── exception/       # 全局异常处理 (BizException, ErrorCode, GlobalExceptionHandler)
│   ├── web/             # 统一响应组件 (Result<T>, PageResult<T>)
│   └── util/            # 通用工具类 (JsonUtil, DateUtil 等)
├── modules/
│   ├── [module]/        # 具体业务模块 (如 user, order)
│   │   ├── api/         # 【对外契约】对外暴露的接口 (interface) 与 DTO/Request/Response，供其他模块调用
│   │   │   ├── *Service.java  # 接口定义 (Interface)
│   │   │   └── dto/           # 重点：Request / Response / DTO 均在此
│   │   │       ├── UserCreateRequest.java
│   │   │       ├── UserQueryDTO.java
│   │   │       └── UserResponse.java
│   │   ├── domain/      # 【业务核心】Service 实现、领域模型、Factory、Repository 接口
│   │   │   ├── *ServiceImpl.java  # 接口实现类
│   │   │   └── model/           # 领域实体对象 (非数据库实体)
│   │   ├── infra/       # 【基础设施】Mapper、RepositoryImpl、外部 API 客户端、模块级配置
│   │   │   ├── mapper/          # MyBatis-Plus Mapper
│   │   │   ├── repository/      # 仓储实现 (PO 转领域模型)
│   │   │   └── client/          # 第三方 API 调用客户端
│   │   └── web/         # 【流量入口】Controller 层：HTTP 请求处理、参数校验 (@Valid)、返回
│   │       └── *Controller.java # 接收参数、调用 api 接口、返回 Result
│   └── ... (其他模块)
└── [Project]Application.java  # Spring Boot 启动类

各层职责边界

层	职责	禁止
web/	接收请求、参数校验（@Valid）、调用本模块 api/ 接口、返回 Result	直接调用其他模块 domain/、直接操作数据库
api/	定义跨模块调用的 interface 和 DTO	包含业务逻辑实现
domain/	业务逻辑、领域对象、事务边界（@Transactional）	直接依赖 Mapper、依赖 web 层
infra/	Mapper、RepositoryImpl（PO ↔ 领域对象转换）、外部调用	包含业务逻辑

3.2 跨模块调用规则

只能通过目标模块的 api/ 接口调用，禁止直接 import 其他模块的 domain/ 或 infra/ 类
跨模块传递使用 api/ 包下定义的 DTO，不传递 PO 或领域对象
循环依赖视为架构错误，立即重构（可通过事件解耦或抽取公共 api）

▼
java
复制代码
// 正确：agent 模块通过 ModelService（api/ 接口）调用 model 模块
@Service
@RequiredArgsConstructor
public class AgentServiceImpl implements AgentService {
    private final ModelService modelService; // 来自 model 模块的 api/ 接口
}

4. 外部服务/高延迟调用规范

适用于：LLM API、第三方 OpenAPI、长连接 SSE、复杂计算等耗时操作。

4.1 线程池配置

普通请求池：核心线程数 20，最大 50，队列容量 100，拒绝策略 CallerRunsPolicy
流式/长连接池：核心线程数 30，最大 80，队列容量 50，拒绝策略 AbortPolicy

4.2 超时配置

普通请求：connectTimeout=5s, readTimeout=120s, writeTimeout=30s
流式请求 (SSE)：connectTimeout=5s, readTimeout=0s（禁止读超时）, writeTimeout=30s

如：

connectTimeout = 5s（TCP 握手超时）
readTimeout = 120s（单次读取超时，仅非流式）
CompletableFuture.get(90, TimeUnit.SECONDS)（总体超时兜底）

4.3 重试策略

普通 LLM：最多 3 次，初始等待 500ms，指数退避 2x，最大等待 10s
Ollama（本地）：最多 5 次，初始等待 2s
仅对网络异常和 5xx 重试，4xx（参数错误）不重试

4.4 熔断与 Fallback

滑动窗口：COUNT_BASED 滑动窗口，20 次请求内失败率 >50% 触发熔断。
慢调用：（>30s）超过 80% 也触发熔断
降级恢复：熔断后等待 30s 进入 half-open，放行 5 次探测
主备路由：配置 fallback 映射（如 providerA -> providerB -> throw BizException）

▼
yaml
复制代码
failure-rate-threshold: 50
slow-call-duration-threshold: 30s
slow-call-rate-threshold: 80
wait-duration-in-open-state: 30
spermitted-calls-in-half-open-state: 5

5. 部署架构

▼
text
复制代码
用户端
  │
  ▼
负载均衡/Ingress (SSL 终止 + 限流 + SSE 配置)
  │
  ├──▶ 前端服务 ([副本数])
  │
  └──▶ 后端服务 Spring Boot ([副本数])
        │
        ├──▶ 主数据库 (MySQL)
        ├──▶ 缓存/会话/限流 (Redis)
        └──▶ [其他中间件/向量库/消息队列]

Ingress 关键配置（SSE 必须）：

▼
yaml
复制代码
nginx.ingress.kubernetes.io/proxy-read-timeout: "300"
nginx.ingress.kubernetes.io/proxy-buffering: "off"
nginx.ingress.kubernetes.io/limit-rps: "20"

Backend 容器规格：requests 512Mi/250m，limits 1Gi/1000m，replicas=2

JVM 启动参数：

▼
dockerfile
复制代码
ENTRYPOINT ["java", "-XX:MaxRAMPercentage=75.0", "-XX:+UseG1GC",
            "-Djava.security.egd=file:/dev/./urandom", "-jar", "app.jar"]

6. 数据库规范

6.1 MySQL 通用字段约定

每张表必须包含以下字段：

▼
sql
复制代码
id          BIGINT          NOT NULL AUTO_INCREMENT,  -- 主键，禁用 UUID
created_at  DATETIME(3)     NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
updated_at  DATETIME(3)     NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
deleted     TINYINT(1)      NOT NULL DEFAULT 0,       -- 逻辑删除标志
PRIMARY KEY (id)

字符集：utf8mb4，排序规则：utf8mb4_unicode_ci
禁用 VARCHAR 无长度约束，text 类 content 字段用 MEDIUMTEXT
金额用 DECIMAL(19,4)，禁用 FLOAT/DOUBLE
布尔用 TINYINT(1)，不用 BIT

6.2 索引设计原则

区分度低的字段不单独建索引（如 deleted、status 枚举），必须与高区分度字段组合
组合索引遵循最左前缀：等值查询字段在左，范围查询字段在右
查询条件中含 deleted，必须将 deleted 纳入索引
每表索引不超过 5 个（含主键），写多读少的表控制在 3 个以内
禁止在 TEXT/BLOB 类型字段上建普通索引，需要时建前缀索引或全文索引

▼
sql
复制代码
-- 正确示例：conversation_id 高区分度在左，deleted 次之，created_at 范围在右
INDEX idx_conv_created (conversation_id, deleted, created_at)

6.3 大表规范

大表阈值：行数 > 500 万或数据量 > 2GB

场景	策略
t_message	按 conversation_id 分区，或按月归档冷数据
知识库向量表	ivfflat 索引，lists = sqrt(行数)
日志类表	只保留 90 天，定期 DELETE + OPTIMIZE TABLE

6.4 分页查询规范

禁止 LIMIT offset, size 深分页（offset > 1000 全表扫描）
对话记录类使用游标分页：

▼
sql
复制代码
-- ✅ 游标分页示例
SELECT * FROM t_table WHERE status = ? AND created_at < ? AND id < ? ORDER BY created_at DESC, id DESC LIMIT 20;

6.5 pgvector 索引规范

▼
sql
复制代码
-- 余弦相似度索引，lists 值 = sqrt(总行数)，行数 <10 万时 lists=100
CREATE INDEX idx_embedding_ivfflat ON knowledge_embedding
USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

-- 查询时设置 probes，精度和速度平衡
SET ivfflat.probes = 10;
SELECT * FROM knowledge_embedding
ORDER BY embedding <=> '[...]'::vector LIMIT 5;

6.6 索引检测措施

开发阶段：启用 p6spy，拦截执行 >10ms 的查询自动 EXPLAIN，type=ALL 时打印警告日志。 CI 阶段：关键查询写 IndexCoverageTest，EXPLAIN 结果中 type=ALL 则测试失败，阻断合并。 生产阶段：定期查询 performance_schema.events_statements_summary_by_digest，找出 sum_no_index_used > 0 的 SQL。

▼
sql
复制代码
SELECT digest_text, count_star AS 执行次数, sum_no_index_used AS 未用索引次数
FROM performance_schema.events_statements_summary_by_digest
WHERE sum_no_index_used > 0
ORDER BY sum_no_index_used DESC LIMIT 20;

7. 编码规范

7.1 命名

类名用 UpperCamelCase，方法名、变量名用 lowerCamelCase，常量用 UPPER_SNAKE_CASE，包名全小写无下划线。
禁止用拼音或拼音缩写命名，禁止单字母变量（循环变量 i/j/k 除外）。
方法名体现动词：查询用 get/list/query，修改用 update，删除用 delete/remove，新增用 create/add，布尔返回值用 is/has/can。
Service 接口不加 I 前缀，实现类加 Impl 后缀（AgentService + AgentServiceImpl）。
数据库表名用 t_ 前缀，列名用 snake_case；PO 类用 Po 后缀，DTO 用 Dto/Request/Response，Mapper 用 Mapper 后缀。

7.2 异常处理

禁止 catch 后 e.printStackTrace() 或空 catch，必须记录日志或向上抛出。
业务异常统一抛 BizException(ErrorCode)，不用 RuntimeException 传递业务语义。
只在顶层（GlobalExceptionHandler）处理并转换为 HTTP 响应，中间层不捕获再包装。
finally 块不写 return，不在 finally 中抛出新异常（会吞掉原始异常）。
NPE 防御：方法返回值优先返回空集合（Collections.emptyList()）而非 null，接口入参用 @NonNull/@Valid 注解声明约束。

7.3 日志

使用 SLF4J 接口 + Logback 实现，类中用 @Slf4j（Lombok），禁止用 System.out.println。
禁止在循环体内打日志，高频路径只在异常分支记录。
占位符格式 log.info("xxx {}", var)，禁止字符串拼接（避免无效 toString 开销）。
日志分级约定：DEBUG=详细调试，INFO=关键业务节点，WARN=可恢复异常或配置缺失，ERROR=需人工介入的故障。生产环境 INFO 级别，日志文件按天滚动，保留 30 天。
LLM 调用必须记录：provider、model、耗时、token 数、是否命中缓存，便于成本分析。

7.4 并发

线程池必须显式创建（ThreadPoolExecutor），禁止用 Executors.newFixedThreadPool（无界队列 OOM）。
ThreadLocal 用完必须 remove()，防止线程池场景下数据泄漏。
加锁粒度最小化：只锁共享变量操作，不锁 I/O 和 LLM 调用；优先用 ReentrantLock 替代 synchronized（可设超时）。
单例 Bean 的成员变量必须是线程安全的：无状态 Service 天然安全；有状态则用 ThreadLocal 或局部变量，禁止用实例变量存请求上下文。
CompletableFuture 异步调用必须指定线程池（supplyAsync(task, llmExecutor)），禁止用默认 ForkJoinPool.commonPool()（会影响其他异步任务）。

8. 认证与授权模块规范

基于 Spring Security + JWT 实现无状态认证，适配前后端分离架构。

8.1 技术选型

认证框架：Spring Security
Token 方案：JWT（推荐 jjwt 库，版本 ≥ 0.12.0）
会话策略：STATELESS，不依赖服务器端 Session

8.2 JWT 规范

Payload 必须包含：userId (subject)、roles (claim)、iat (签发时间)、exp (过期时间)
密钥管理：通过环境变量注入，禁止硬编码
Token 有效期：短期 Token（30 分钟） + Refresh Token（7 天）
安全要求：使用 HMAC-SHA256 或更强算法签名

8.3 Security 配置规范

CSRF：前后端分离场景禁用
会话创建：设为 STATELESS
白名单：登录接口、文档接口、健康检查必须放行
过滤器：自定义 OncePerRequestFilter 提取并验证 Authorization Header

8.4 权限控制规范

方法级：使用 @PreAuthorize("hasRole('XXX')") 或 @PreAuthorize("hasAnyRole()")
资源级：建议遵循 模块:操作 格式，如 agent:delete、model:create
防越权：操作数据前校验 userId 与数据 owner 是否匹配

8.5 接口规范

登录：POST /api/auth/login，返回 accessToken + refreshToken + expiresAt
登出：POST /api/auth/logout，可选支持服务端 Token 黑名单
刷新：POST /api/auth/refresh，使用 refreshToken 换取新 accessToken

8.6 请求头规范

认证头格式：Authorization: Bearer <token>
可选请求头：X-Request-Id（链路追踪，由网关或客户端生成

9. API 文档生成规范

推荐使用 Knife4j（基于 SpringDoc OpenAPI 3.x），支持 OpenAPI 3.0 标准。

9.1 依赖选型

springdoc-openapi-starter-webmvc-ui (≥ 2.5.0)
knife4j-openapi3-jakarta-spring-boot-starter (≥ 4.5.0)（可选，提供增强 UI）

9.2 注解使用规范

注解	位置	说明
`@Tag`	Controller 类	模块名称，如 `@Tag(name = "用户管理")`
`@Operation`	方法	接口描述，如 `@Operation(summary = "创建用户")`
`@Parameter`	方法参数	参数说明
`@Schema`	DTO 类/字段	类和字段描述，必填字段设置 `requiredMode`

9.3 全局配置规范

通过 @Configuration 配置 OpenAPI Bean，设置 title、version、description
支持多版本分组：@GroupedOpenApi 按路径匹配分组（如 /api/v1/**）

9.4 安全配置

生产环境必须关闭：springdoc.swagger-ui.enabled=false、knife4j.production=true
开发环境可开启基础认证：配置访问文档的 username/password

9.5 枚举文档化

枚举字段添加 @Schema(description = ...) 说明
使用 @JsonValue 标注序列化值

10. 性能瓶颈优先级

规则 ID	优先级	风险领域	AI 自动检测规则	自动修复策略
R-PERF-001	P0	高可用	检测同步调用外部 API/LLM 且无超时/隔离配置	自动改用线程池隔离 + `@CircuitBreaker` + Fallback 逻辑
R-PERF-002	P0	数据库性能	检测 WHERE/JOIN/ORDER BY 字段无索引对应	自动生成 `CREATE INDEX` 语句 + 提醒 Explain 验证
R-PERF-003	P0	并发安全	检测分布式写操作无锁保护 + 无幂等设计	自动添加 Redisson 分布式锁 + 幂等 Key 校验
R-PERF-010	P1	数据库性能	检测 `LIMIT offset, size` 且 offset > 1000	自动改写为游标分页：`WHERE id > lastId ORDER BY id LIMIT n`
R-PERF-011	P1	数据库性能	检测循环内执行单条 SQL (N+1 查询)	自动替换为 `IN` 批量查询 + 结果集 Map 映射
R-PERF-012	P1	资源可用性	检测未配置或参数不合理的连接池	自动生成推荐配置：`maxPoolSize = CPU*2`, `connectionTimeout = 3000ms`
R-PERF-020	P2	内存安全	检测一次性加载全量结果集/大文件到内存	自动改写为流式处理：`Stream<List<T>>` + `@ResultOrdered`
R-PERF-021	P2	安全合规	检测日志打印敏感字段 (密码/手机号/身份证)	自动替换为脱敏工具调用：`DesensitizeUtil.mask()`

11. 遗留问题清单（后续版本优化）

11.1 安全扩展（高优先级）

防 SQL 注入、XSS、CSRF、接口防重放攻击方案
敏感数据（手机号、身份证）脱敏策略
敏感接口参数加密传输方案

11.2 测试规范

单元测试规范：JUnit 5 + Mockito，核心代码覆盖率 ≥ 80%
集成测试规范：TestContainers + Mock 外部服务
性能测试规范：压测流程与基线定义

11.3 数据库扩展

分布式事务方案（Saga、TCC、Seata）
缓存穿透/击穿/雪崩应对策略及一致性方案
大表水平拆分策略

11.4 API 设计扩展

全局校验异常处理与自定义校验注解
接口幂等性设计方案（Token 机制、唯一索引等）

11.5 运维与部署

CI/CD 流水线规范（代码检查、构建、部署）
多环境配置分离（dev/test/prod）与配置中心集成
链路追踪（TraceId + MDC + APM 接入）

11.6 代码质量

Git 工作流与 Code Review 检查清单
枚举设计规范（状态码、业务类型、字典映射）
文档中占位符需根据实际项目替换

Claude.md