文档说明文档定位团队全员统一 AI 编码标准、开发流程、工具规范、落地模板正式生产制度文件。覆盖范围Windows/Mac/Linux 全平台、Maven/Gradle 双构建、零基础部署、企业级Java编码规范带正负示例、全套可复用模板、8大生产高阶场景、全量避坑清单、架构师级标准工作流、Anthropic Java API 实战。技术栈标准JDK17 SpringBoot3.x MySQL8 MyBatis-Plus Lombok JUnit5生效规则所有使用 Claude Code 进行开发的 Java 项目必须严格遵循本手册规范统一代码风格、质量、工程结构杜绝AI幻觉、代码不规范、架构混乱问题。第一章 全平台环境零基础部署规范1.1 Mac / Linux 安装与启动# 官方一键安装 curl -fsSL https://claude.com/install | bash # 账号登录支持订阅账号 / API Key 两种方式 claude login # 项目启动标准流程 cd 项目根目录 claude1.2 Windows PowerShell 安装与启动# 官方一键安装 irm https://claude.com/install | iex # 登录 claude login # 进入项目启动 cd 项目根目录 claude1.3 项目前置依赖强制要求JDK 17 及以上Claude Code Java LSP 强制依赖低版本会出现语法解析异常构建工具Maven3.8 或 Gradle7可选增强jdtls Java语言服务提供代码校验、语法检查、规范提示第二章 项目AI强制核心配置根治AI幻觉强制要求所有项目必须包含以下三份配置文件缺一不可作为AI编码唯一依据。2.1 项目规范核心文件CLAUDE.md根目录必存# 团队统一AI开发规范Java SpringBoot 企业级标准 ## 基础技术栈 - 项目框架Spring Boot 3.x - JDK 版本17 - 构建工具Maven / Gradle - 数据库MySQL 8.0 - ORM 框架MyBatis-Plus 最新稳定版 - 日志框架SLF4J Lombok Slf4j - 测试框架JUnit 5 Mockito - 代码标准阿里巴巴Java开发手册 团队自定义规范 ## 标准工程包结构严格强制执行 com.xxx.project ├── config # 全局配置、Bean、拦截器、跨域、分页插件、线程池 ├── controller # 接口层仅接收参数、调用业务、统一返回禁止写业务逻辑 ├── service # 业务接口层 │ └── impl # 业务实现层所有业务逻辑实现 ├── mapper # DAO数据访问层仅做数据库操作 ├── entity # 数据库实体DO严格对应数据表字段 ├── dto # 前端入参新增/修改/查询条件 ├── vo # 前端出参接口响应数据 ├── exception # 自定义业务异常、全局异常处理器 ├── common # 全局常量、枚举、统一返回体 ├── util # 通用工具类 ## 代码强制约束规则 1. 所有接口必须添加 Valid 参数校验禁止裸参数接收 2. 数据库操作优先使用MyBatis-Plus Lambda语法禁止硬编码SQL 3. 所有接口统一返回 ResultT禁止直接返回实体、List、Map 4. 强制空指针、集合空判断杜绝NPE风险 5. 新增业务必须编写JUnit5单元测试覆盖正常、异常、边界场景 6. 所有类、核心方法、复杂逻辑必须添加中文注释 7. 严格单一职责单方法代码不超过80行禁止超大类、万能方法 8. 禁止魔法值所有固定参数统一维护在常量类 9. 业务事务必须配置 Transactional严格遵循事务生效规则 10. 手机号、密码、身份证等敏感字段必须脱敏输出、禁止明文日志打印 11. 所有分页接口必须使用MyBatis-Plus分页插件禁止手写分页 12. 事务方法必须为public禁止内部调用、非事务方法调用导致事务失效 13. 禁止在Controller写业务逻辑、数据库操作 14. 异常统一抛出业务异常禁止直接返回错误字符串 ## 统一命名规范 - 类名大驼峰望文知意 - 方法/变量小驼峰动词名词 - 常量全大写下划线分隔 - 数据表、接口路径小写下划线分隔 - DTO后缀xxxDTO入参 - VO后缀xxxVO出参 ## AI开发强制输出规则 1. 禁止生成冗余import、废弃代码、无效注释、空方法 2. 严格贴合现有项目结构不随意新建包、修改架构 3. 禁止私自新增、修改、删除Maven/Gradle依赖依赖变更必须人工审核 4. 代码生成后必须保证编译通过、无语法错误 5. 新增文件必须补齐标准头部注释、功能说明 6. 严格遵循团队统一代码风格、注释规范、异常规范 7. 修复Bug、重构代码不得改动原有正常业务逻辑2.2 免确认运行配置.claude/settings.local.json兼容Maven、Gradle双构建工具自动放行编译、测试、打包命令避免频繁弹窗确认。{ allowedCommands: [ mvn clean compile, mvn clean package, mvn test, mvn spring-boot:run, mvn dependency:tree, mvn jacoco:report, ./gradlew clean build, ./gradlew test, ./gradlew bootRun, ./gradlew dependencies ], autoConfirm: true, maxFileWriteSize: 204800, timeout: 120000 }2.3 AI专属.gitignore 规范配置防止Claude缓存、会话文件、临时文件污染代码仓库。# Claude Code AI缓存文件 .claude/sessions/ .claude/cache/ claude-logs/ *.claude.tmp # 项目编译缓存 target/ build/ *.iml .idea/ *.class第三章 团队通用基础组件模板全员统一·直接投产所有项目必须使用以下统一组件禁止自定义不同格式工具类、返回体、异常处理。3.1 统一全局返回体 ResultTimport lombok.Data; /** * 全局统一接口返回结果 * 团队统一标准所有接口强制使用 */ Data public class ResultT { private Integer code; private String msg; private T data; public static T ResultT success() { return result(200, 操作成功, null); } public static T ResultT success(T data) { return result(200, 操作成功, data); } public static T ResultT fail(Integer code, String msg) { return result(code, msg, null); } private static T ResultT result(Integer code, String msg, T data) { ResultT result new Result(); result.setCode(code); result.setMsg(msg); result.setData(data); return result; } }3.2 自定义业务异常/** * 全局自定义业务异常 * 业务报错统一抛出此异常 */ public class BusinessException extends RuntimeException { private final Integer code; private final String msg; public BusinessException(Integer code, String msg) { super(msg); this.code code; this.msg msg; } public Integer getCode() { return code; } public String getMsg() { return msg; } }3.3 全局统一异常处理器import lombok.extern.slf4j.Slf4j; import org.springframework.validation.BindException; import org.springframework.web.bind.MethodArgumentNotValidException; import org.springframework.web.bind.annotation.ExceptionHandler; import org.springframework.web.bind.annotation.RestControllerAdvice; /** * 全局异常统一拦截处理 * 统一所有异常返回格式禁止接口返回原生异常信息 */ Slf4j RestControllerAdvice public class GlobalExceptionHandler { /** * 表单、JSON参数校验异常 */ ExceptionHandler(MethodArgumentNotValidException.class) public ResultVoid validException(MethodArgumentNotValidException e) { String msg e.getBindingResult().getFieldError().getDefaultMessage(); return Result.fail(400, msg); } /** * 绑定参数异常 */ ExceptionHandler(BindException.class) public ResultVoid bindException(BindException e) { String msg e.getFieldError().getDefaultMessage(); return Result.fail(400, msg); } /** * 自定义业务异常 */ ExceptionHandler(BusinessException.class) public ResultVoid businessException(BusinessException e) { return Result.fail(e.getCode(), e.getMsg()); } /** * 系统全局未知异常 */ ExceptionHandler(Exception.class) public ResultVoid globalException(Exception e) { log.error(系统未知异常, e); return Result.fail(500, 系统繁忙请稍后重试); } }3.4 项目公共常量类/** * 全局公共常量 * 所有固定参数统一在此维护杜绝魔法值 */ public class CommonConstant { // 接口响应码 public static final int SUCCESS_CODE 200; public static final int PARAM_ERROR_CODE 400; public static final int SERVER_ERROR_CODE 500; // 分页默认参数 public static final Integer DEFAULT_PAGE_NUM 1; public static final Integer DEFAULT_PAGE_SIZE 10; }3.5 通用分页VOimport lombok.Data; import java.util.List; /** * 全局统一分页返回对象 */ Data public class PageVOT { private ListT list; private Long total; private Integer pageNum; private Integer pageSize; }3.6 MyBatis-Plus 分页插件配置必配import com.baomidou.mybatisplus.extension.plugins.MybatisPlusInterceptor; import com.baomidou.mybatisplus.extension.plugins.inner.PaginationInnerInterceptor; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; /** * MyBatis-Plus 全局插件配置 * 分页功能必备所有分页接口依赖此配置 */ Configuration public class MyBatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); // 分页插件 interceptor.addInnerInterceptor(new PaginationInnerInterceptor()); return interceptor; } }第四章 Java企业级编码规范带正负对比示例4.1 命名规范强制校验4.1.1 类命名// ✅ 正确大驼峰、语义清晰、职责单一 RestController public class UserController {} Service public class OrderServiceImpl {} // ❌ 错误小驼峰、无意义、拼音、乱数字 Service public class userService {} Controller public class TestDemo1 {}4.1.2 方法命名// ✅ 正确动词名词语义明确 public UserVO getUserById(Long userId); public void updateUserStatus(Long userId, Integer status); public PageVOOrderVO listOrderPage(OrderQueryDTO queryDTO); // ❌ 错误无意义、简写、大小写混乱 public void doData(); public String getinfo();4.1.3 常量命名// ✅ 正确全大写下划线 public static final int MAX_LOGIN_FAIL_COUNT 5; public static final String USER_TOKEN_PREFIX user:token:; // ❌ 错误小驼峰、混合命名 public static final int maxCount 5;4.2 注释规范4.2.1 类注释/** * 用户管理控制器 * 负责用户新增、查询、修改、状态管理等相关接口 * author 团队开发组 * date 2026-04-27 */ RestController RequestMapping(/api/user)4.2.2 方法注释/** * 根据用户ID查询用户详情 * param userId 用户唯一ID * return 用户详情VO信息 * throws BusinessException 用户不存在时抛出异常 */ UserVO getUserDetail(Long userId);4.3 Controller 层规范核心原则只收参、只校验、只转发、只返回不写业务逻辑// ✅ 标准规范写法 Slf4j RestController RequestMapping(/api/user) public class UserController { PostMapping(/create) public ResultLong createUser(Valid RequestBody UserCreateDTO dto) { log.info(新增用户入参{}, dto.getUsername()); Long userId userService.createUser(dto); return Result.success(userId); } } // ❌ 错误写法Controller写业务逻辑、数据库操作、无校验 PostMapping(/create) public Result createUser(RequestBody UserCreateDTO dto){ User user new User(); user.setUsername(dto.getUsername()); userMapper.insert(user); return Result.success(); }4.4 Service 业务层规范事务异常日志// ✅ 标准事务规范 Override Transactional(rollbackFor Exception.class, propagation Propagation.REQUIRED) public Boolean createOrder(OrderCreateDTO dto) { // 参数判空 if (Objects.isNull(dto) || Objects.isNull(dto.getSkuId())) { throw new BusinessException(400, 订单参数不能为空); } // 业务逻辑 stockMapper.deductStock(dto.getSkuId(), dto.getQuantity()); Order order buildOrder(dto); orderMapper.insert(order); return true; } // ❌ 错误无事务、无异常、无判空、裸写逻辑 public boolean createOrder(OrderCreateDTO dto){ stockMapper.deductStock(dto.getSkuId(),dto.getQuantity()); Order order buildOrder(dto); orderMapper.insert(order); return true; }4.5 数据传输规范DTO/VO/DO 分层核心原则数据库实体不对外暴露入参出参严格隔离// DO数据库实体仅对应数据库 Data TableName(sys_user) public class User { TableId(type IdType.AUTO) private Long id; private String username; private String password; private Integer status; TableField(fill FieldFill.INSERT) private LocalDateTime createTime; } // DTO前端入参校验参数 Data public class UserCreateDTO { NotBlank(message 用户名不能为空) Length(min 2, max 20, message 用户名长度必须2-20位) private String username; NotBlank(message 密码不能为空) private String password; Email(message 邮箱格式错误) private String email; } // VO前端出参脱敏、过滤敏感字段 Data public class UserVO { private Long id; private String username; private String email; private Integer status; private LocalDateTime createTime; }4.6 空指针集合处理规范// ✅ 标准安全写法 ListUser userList Optional.ofNullable(list).orElse(Collections.emptyList()); ListUserVO voList userList.stream() .map(this::convert) .collect(Collectors.toList()); // ❌ 错误直接调用size()、未判空 if(list.size() 0){}4.7 日志规范// ✅ 规范info打印业务error打印堆栈 log.info(用户登录成功用户名{}, username); log.error(用户登录失败用户名{}, username, e); // ❌ 错误明文打印密码、不打印堆栈 log.info(登录参数{}, dto); log.error(登录失败);第五章 Claude Code 高频内置指令Java专用# 查看完整项目目录结构快速熟悉项目 /tree # 全局关键词检索排查硬编码、指定注解、漏洞代码 /search 关键词 # 查看AI所有代码修改差异 /diff # 全局格式化Java代码统一风格 /format # 清空会话上下文解决上下文过载、错乱 /clear # 查看当前会话所有已修改文件 /changed # 解析类/方法底层逻辑、业务流程、问题风险 /explain 全类路径 # 批量自动补全缺失注释 /docs第六章 团队标准化8大生产级Prompt模板直接复制即用6.1 标准CRUD完整生成日常开发核心严格遵循项目CLAUDE.md团队规范完成【模块名称】完整企业级CRUD开发 1. 生成标准DO实体包含注释、主键、自动填充字段 2. 生成新增/修改/查询DTO添加完整参数校验注解 3. 生成前端响应VO脱敏敏感字段 4. Mapper继承BaseMapper使用MyBatis-Plus规范写法 5. 编写Service接口与ServiceImpl实现类增加事务、判空、异常处理、日志 6. 编写RESTful风格Controller接口统一返回ResultT 7. 实现分页查询、详情查询、新增、修改、删除完整功能 8. 生成JUnit5单元测试覆盖正常场景、参数异常、数据不存在场景 要求代码规范整洁、无冗余、注释齐全、可直接编译运行。6.2 线上Bug定位与修复Debug专用帮我分析并修复当前项目报错严格遵循团队规范 1. 解析报错堆栈信息精准定位报错代码行与根因 2. 排查空指针、参数非法、事务失效、N1查询、依赖冲突、并发安全问题 3. 输出结构化问题分析报告 4. 修复代码保证不改动原有正常业务逻辑 5. 执行编译校验确保编译通过 6. 必要时补充单元测试验证修复效果 粘贴报错堆栈6.3 代码重构性能优化对【指定包/类路径】代码进行企业级重构优化遵循CLAUDE.md团队规范 1. 拆分超长方法、超大类遵循单一职责原则 2. 修复潜在空指针、资源泄漏、事务漏洞、参数缺失问题 3. 消除所有魔法值统一使用全局常量 4. 优化N1数据库查询、循环IO、低效遍历等性能问题 5. 清理冗余import、废弃代码、无效注释 6. 规范日志打印、异常抛出格式 7. 重构后保证原有业务逻辑完全不变编译、测试全部通过 先输出优化报告再执行代码修改。6.4 通用组件快速开发基于SpringBoot3企业级规范和团队CLAUDE.md标准创建【组件名称】通用组件 1. 放置在项目对应规范包路径下 2. 适配JDK17新特性代码严谨、边界完善 3. 完善异常处理、参数兼容、容错机制 4. 附带详细使用示例 5. 代码可直接投产使用 可选组件跨域配置、线程池配置、日期工具、加密工具、序列化配置6.5 上线前代码全量审计对【全项目/指定模块】做完整企业级代码审计 1. 代码异味不规范命名、冗余代码、长方法、魔法值 2. 潜在Bug空指针、事务失效、并发漏洞、参数未校验 3. 性能风险N1查询、资源未释放、慢查询、循环依赖 4. 安全风险敏感信息明文日志、接口未鉴权、字段未脱敏 5. 规范问题不符合阿里Java规范、团队自定义规范 输出结构化审计报告风险等级代码位置问题描述修复方案自动修复低风险问题高风险问题给出详细改造建议。6.6 中间件开发Redis/MQ遵循团队规范基于SpringBoot实现【Redis/RocketMQ/Kafka】生产级能力 1. 编写标准化配置类、序列化配置、连接优化 2. 封装通用工具类实现常用业务方法 3. 增加超时控制、异常重试、容错降级 4. 规避生产经典问题缓存穿透/击穿/雪崩、消息重复消费、消息丢失、消息积压 5. 编写使用示例与单元测试保证可直接投产6.7 事务并发安全改造全局检查并优化项目事务与并发安全逻辑 1. 修复所有事务失效场景非public方法、内部调用、异常被捕获 2. 合理配置Transactional传播机制、隔离级别 3. 针对并发场景增加本地锁/分布式锁控制 4. 排查并解决超卖、数据覆盖、并发脏写问题 5. 输出改造说明保证事务生效、并发安全6.8 JWT登录鉴权模块开发基于SpringBoot实现团队规范企业级JWT认证授权模块 1. 实现登录、注销、令牌刷新核心接口 2. 编写全局Token拦截器统一接口鉴权 3. 配置匿名放行接口、权限基础控制 4. 实现密码加密、Token过期、续签机制 5. 整合全局异常处理、参数校验、统一Result返回格式第七章 高频致命坑点全集团队强制避坑依赖冲突坑AI易私自引入不兼容版本依赖每次开发完成必须执行mvn dependency:tree校验依赖冲突禁止AI私自修改pom事务幻觉坑AI经常忽略「事务方法必须public、内部调用失效、受检异常不回滚」规则所有事务代码必须人工复核分页缺失坑AI生成CRUD易遗漏分页插件配置项目统一全局配置分页插件禁止手写分页敏感数据泄露坑禁止AI明文打印手机号、密码、身份证所有敏感字段强制脱敏上下文过载坑单会话禁止开发多模块按业务拆分独立会话定期/clear重置上下文代码误删覆盖坑核心业务修改前必须执行/diff核对变更防止AI误删逻辑魔法值坑禁止AI生成硬编码固定参数全部统一常量管理NPE空指针坑强制所有对象、集合做判空处理禁止直接调用属性和方法第八章 架构师级团队标准AI开发工作流强制流程所有AI开发必须严格遵循此流程统一团队开发节奏杜绝混乱、返工、不规范。项目初始化新建/接入项目 → 放入CLAUDE.md 权限配置 gitignore项目认知启动Claude让AI通读项目结构、技术栈、规范、依赖不做任何代码修改基础组件先行优先完善统一返回、全局异常、分页配置、工具类等公共能力模块会话隔离按用户、订单、库存、支付拆分独立会话上下文互不干扰标准化业务开发CRUD生成 → 参数校验 → 事务控制 → 日志完善 → 异常处理质量校验闭环/diff核对变更 → mvn compile编译校验 → 单元测试覆盖优化审计代码格式化 → 代码异味修复 → 性能优化 → 安全漏洞扫描上线收尾清理冗余代码、统一风格、整体回归、人工复核核心逻辑第九章 Java Claude API 生产级实战同步异步9.1 Maven 核心依赖dependency groupIdcom.anthropic/groupId artifactIdanthropic-java/artifactId version0.7.0/version /dependency !-- 异步响应式支持 -- dependency groupIdio.projectreactor/groupId artifactIdreactor-core/artifactId /dependency9.2 同步调用 Demoimport com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.messages.MessageParam; import com.anthropic.models.messages.Role; /** * Claude API 同步调用示例 * 用于代码审查、代码优化、Bug分析 */ public class ClaudeSyncDemo { public static void main(String[] args) { AnthropicClient client AnthropicOkHttpClient.fromEnv(); String result client.messages().create(req - req .model(claude-3-5-sonnet-latest) .maxTokens(2048) .messages(MessageParam.builder() .role(Role.USER) .content(帮我审查这段Java代码找出漏洞、性能问题并给出优化方案) .build()) ).content().get(0).text(); System.out.println(AI分析结果 result); } }9.3 异步调用 Demo生产推荐import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; /** * Claude API 异步调用示例 * 适用于后台异步代码分析、日志智能解析 */ public class ClaudeAsyncDemo { public static void main(String[] args) { AnthropicClient client AnthropicOkHttpClient.fromEnv(); client.messages().createAsync(req - req .model(claude-3-5-sonnet-latest) .maxTokens(2048) .userMessage(帮我优化SpringBoot事务代码修复事务失效风险) ).subscribe(resp - { System.out.println(AI异步返回结果 resp.content().get(0).text()); }); } }第十章 手册全覆盖验收清单本手册已100%全覆盖无遗漏满足团队AI标准化开发全部需求✅ Windows/Mac/Linux 全平台零基础部署✅ Maven/Gradle 双构建工具适配✅ 企业级Java全套编码规范带正负代码示例✅ 团队统一三份核心配置文件✅ 6套生产通用基础组件源码直接投产✅ Claude Code 全套高频指令✅ 8大生产高阶场景万能Prompt模板✅ 全量生产避坑指南✅ 架构师级标准化开发工作流✅ 同步异步 Claude Java API 实战代码