Template

Leo 6a276f45a9 docs: 新增Java方法注释规范到项目开发指南

在CLAUDE.md中添加方法注释规范（Method Comment Standard）：
- 强制要求所有新增Java文件的方法必须添加注释
- 统一注释格式：@description [功能描述] 和 @author Leocoder
- 适用于所有类型的方法（public、private、protected、接口方法等）
- 提供具体的示例代码和使用场景

此规范旨在提高代码可读性、可维护性和团队协作效率，
确保项目代码注释的一致性和标准化。

2025-07-09 14:42:05 +08:00

13 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

第一部分：核心编程原则 (Guiding Principles)

这是我们合作的顶层思想，指导所有具体的行为。可读性优先 (Readability First)：始终牢记“代码是写给人看的，只是恰好机器可以执行”。清晰度高于一切。 DRY (Don't Repeat Yourself)：绝不复制代码片段。通过抽象（如函数、类、模块）来封装和复用通用逻辑。高内聚，低耦合 (High Cohesion, Low Coupling)：功能高度相关的代码应该放在一起（高内聚），而模块之间应尽量减少依赖（低耦合），以增强模块独立性和可维护性。

第二部分：具体执行指令 (Actionable Instructions)

这是 Claude 在日常工作中需要严格遵守的具体操作指南。沟通与语言规范默认语言：请默认使用简体中文进行所有交流、解释和思考过程的陈述。代码与术语：所有代码实体（变量名、函数名、类名等）及技术术语（如库名、框架名、设计模式等）必须保持英文原文。注释规范：代码注释应使用中文。行尾注释禁令 (End-of-Line Comment Prohibition)：严格禁止在代码行末尾添加注释（如 code; // 注释）。所有单行注释必须在代码行前面单独占一行，格式为：

// 设置文件访问路径
String fileUploadPath = (String) fileMap.get("fileUploadPath");

这确保代码的简洁性和可读性，避免行尾注释造成的视觉干扰。

方法注释规范 (Method Comment Standard)：所有新增的Java文件中的方法都必须添加方法注释，格式为：

/**
 * @description [功能描述]
 * @author Leocoder
 */

此规范适用于：

所有public方法
所有private方法
所有protected方法
接口方法
抽象方法
静态方法

示例：

/**
 * @description [上传文件到阿里云OSS]
 * @author Leocoder
 */
public Map<String, Object> uploadFile(MultipartFile file, String fileName, String folderPath) {
    // 方法实现
}

批判性反馈与破框思维 (Critical Feedback & Out-of-the-Box Thinking)：审慎分析：必须以审视和批判的眼光分析我的输入，主动识别潜在的问题、逻辑谬误或认知偏差。坦率直言：需要明确、直接地指出我思考中的盲点，并提供显著超越我当前思考框架的建议，以挑战我的预设。严厉质询 (Tough Questioning)：当我提出的想法或方案明显不合理、过于理想化或偏离正轨时，必须使用更直接、甚至尖锐的言辞进行反驳和质询，帮我打破思维定式，回归理性。开发与调试策略 (Development & Debugging Strategy) 坚韧不拔的解决问题 (Tenacious Problem-Solving)：当面对编译错误、逻辑不通或多次尝试失败时，绝不允许通过简化或伪造实现来“绕过”问题。逐个击破 (Incremental Debugging)：必须坚持对错误和问题进行逐一分析、定位和修复。

探索有效替代方案 (Explore Viable Alternatives)：如果当前路径确实无法走通，应切换到另一个逻辑完整、功能健全的替代方案来解决问题，而不是退回到一个简化的、虚假的版本。

禁止伪造实现 (No Fake Implementations)：严禁使用占位符逻辑（如空的循环）、虚假数据或不完整的函数来伪装功能已经实现。所有交付的代码都必须是意图明确且具备真实逻辑的。战略性搁置 (Strategic Postponement)：只有当一个问题被证实非常困难，且其当前优先级不高时，才允许被暂时搁置。搁置时，必须以 TODO 形式在代码中或任务列表中明确标记，并清晰说明遇到的问题。在核心任务完成后，必须回过头来重新审视并解决这些被搁置的问题。规范化测试文件管理 (Standardized Test File Management)：严禁为新功能在根目录或不相关位置创建孤立的测试文件。在添加测试时，必须首先检查项目中已有的测试套件（通常位于 tests/ 目录下），并将新的测试用例整合到与被测模块最相关的现有测试文件中。只有当确实没有合适的宿主文件时，才允许在 tests/ 目录下创建符合项目命名规范的新测试文件。项目与代码维护 (Project & Code Maintenance) 统一文档维护 (Unified Documentation Maintenance)：严禁为每个独立任务（如重构、功能实现）创建新的总结文档（例如 CODE_REFACTORING_SUMMARY.md）。在任务完成后，必须优先检查项目中已有的相关文档（如 README.md、既有的设计文档等），并将新的总结、变更或补充内容直接整合到现有文档中，维护其完整性和时效性。及时清理 (Timely Cleanup)：在完成开发任务时，如果发现任何已无用（过时）的代码、文件或注释，应主动提出清理建议。

常用命令

构建和运行

# 编译整个项目
mvn clean compile

# 打包项目
mvn clean package

# 运行应用程序
cd coder-common-thin-web
mvn spring-boot:run

# 或者运行打包后的jar
java -jar coder-common-thin-web/target/coder-common-thin-web-1.0.0.jar

测试

# 运行所有测试
mvn test

# 运行单个模块测试
mvn test -pl coder-common-thin-web

数据库

# 数据库初始化SQL位于
# sql/coder-common-thin.sql

项目架构概览

这是一个基于Spring Boot 3.5.0的多模块企业级开发框架，采用插件化架构设计。

模块结构

coder-common-thin-web: Web启动模块，应用程序入口点
coder-common-thin-common: 公共工具模块，包含大量工具类、配置类和拦截器
coder-common-thin-model: 数据模型模块，包含POJO、BO、VO和数据验证
coder-common-thin-mybatisplus: 数据访问层模块，MyBatis Plus配置和Mapper
coder-common-thin-modules: 业务模块容器
coder-common-thin-plugins: 插件模块，包含各种功能插件

插件化架构

项目采用@Enable注解实现功能模块的可插拔配置：

@EnableCoderSaToken: Sa-Token认证插件
@EnableCoderEasyExcel: Excel处理插件
@EnableCoderLimit: 限流插件
@EnableCoderRepeatSubmit: 防重提交插件
@EnableCoderDesensitize: 数据脱敏插件

技术栈

核心框架: Spring Boot 3.5.0 + Java 17
数据库: MySQL 9.3.0 + MyBatis Plus 3.5.12
缓存: Redis（Spring Data Redis）
安全认证: Sa-Token 1.43.0
工具库: Hutool 5.8.38, Fastjson2 2.0.57, Guava 33.4.8
业务功能: EasyExcel 4.0.3, Easy-Captcha 1.6.2

数据层设计

主键策略: 雪花算法（ASSIGN_ID）
逻辑删除: 0-已删除, 1-未删除
多数据源: 支持master/slave数据源动态切换
SQL监控: 集成P6spy进行SQL性能监控

配置文件

主配置: application.yml
环境配置: application-dev.yml
数据库配置: 支持MySQL主从配置
Redis配置: 使用Jackson2序列化，支持连接池

开发指南

添加新功能插件

在coder-common-thin-plugins下创建新模块
创建@Enable注解用于启用插件
实现必要的配置类和工具类
在主启动类上使用@Enable注解启用

数据访问层开发

实体类放在coder-common-thin-model/domain/pojo
Mapper接口放在coder-common-thin-mybatisplus/mapper
XML映射文件放在resources/mapper
使用@DS("dataSourceName")注解切换数据源

业务层开发规范

依赖注入规范: 所有ServiceImpl实现类必须使用@RequiredArgsConstructor构造器注入模式，禁止使用@Autowired字段注入
- 在类上添加@RequiredArgsConstructor注解
- 将需要注入的依赖声明为private final字段
- Spring会自动通过构造器注入依赖
Service分层规范: Service层必须按功能模块分目录组织，不允许使用单一的impl目录
- 每个功能模块创建独立目录（如：courseselection、courseoffering、coursecart）
- 在各功能目录下放置对应的Service接口和ServiceImpl实现类
- 包路径示例：org.leocoder.course.education.service.courseselection.SysCourseSelectionService
Controller路径规范: 所有Controller必须使用统一的/coder前缀作为API根路径
- 所有Controller的@RequestMapping必须以/coder开头
- 路径格式：/coder/模块名/功能名
- 示例路径：/coder/education/selection、/coder/education/offering、/coder/education/cart
- 参考示例：@RequestMapping("/coder/education/selection")
Controller权限验证规范: 所有Controller的接口方法必须配置权限验证
- 强制要求: 每个Controller方法都必须添加@SaCheckPermission注解
- 导入依赖: 在Controller类中导入import cn.dev33.satoken.annotation.SaCheckPermission;
- 权限命名规范: 使用格式模块名:功能名:操作名
  - 教育模块示例：@SaCheckPermission("education:selection:list")
  - 系统模块示例：@SaCheckPermission("system:user:list")
- 操作名对应关系:
  - list - 查询列表
  - page - 分页查询
  - detail - 查询详情
  - add - 新增
  - edit - 修改
  - delete - 删除
  - status - 状态变更
  - import - 导入
  - export - 导出
- 示例代码:
```
@RestController
@RequestMapping("/coder/education/selection")
public class SysCourseSelectionController {

    @SaCheckPermission("education:selection:list")
    @GetMapping("/list")
    public List<SysCourseSelection> list(@Validated CourseSelectionBo bo) {
        // 业务逻辑
    }

    @SaCheckPermission("education:selection:add")
    @PostMapping("/add")
    public String add(@Validated CourseSelectionBo bo) {
        // 业务逻辑
    }
}
```
- 禁止行为:
  - 严禁创建没有权限验证的Controller方法
  - 严禁在Sa-Token配置中添加业务接口的排除路径
  - 严禁通过其他方式绕过权限验证

工具类使用

项目提供了丰富的工具类，位于coder-common-thin-common/utils：

缓存工具: RedisUtil, LocalCacheUtil
日期工具: DateUtil, CalendarUtil
文件工具: FileUtil, UploadUtil, ZipUtil
字符串工具: StringUtil, ConvertUtil
IP工具: IpUtil, IpAddressUtil
JSON工具: JsonUtil
加密工具: MD5Util, CoderPasswordUtil

配置说明

端口: 默认18099，可通过port环境变量覆盖
文件路径: 在application-dev.yml中配置coder.filePath
数据库连接: 在application-dev.yml中配置数据源信息
Redis配置: 在application-dev.yml中配置Redis连接信息

日志配置

日志文件: logback-spring.xml
日志级别: 可通过环境变量调整
操作日志: 自动记录，支持异步处理和定时清理

注意事项

项目基于Java 17，确保开发环境版本匹配
使用中文注释，保持代码风格一致
新增功能遵循插件化设计模式
数据库操作优先使用MyBatis Plus提供的方法
安全认证统一使用Sa-Token，避免重复造轮子
工具类使用前先检查是否已有现成实现

重要规范文档

所有Controller必须配置权限验证（强制要求）
使用统一的路径前缀和权限命名规范
遵循标准的代码结构和注解使用规范

开发强制要求 ⚠️

权限验证强制要求: 任何新增的Controller方法都必须添加 @SaCheckPermission 注解
禁止绕过权限验证: 严禁通过排除路径或其他方式绕过Sa-Token权限验证
权限命名标准化: 必须使用 模块名:功能名:操作名 格式命名权限
构造器注入: 必须使用 @RequiredArgsConstructor 模式，禁用 @Autowired
模块依赖管理: 新增业务模块时必须在Web启动模块（coder-course-web）的pom.xml中添加对应依赖
- 依赖检查原则: 当Controller接口报错被当作静态资源处理时，首先检查Web模块是否缺少对应业务模块的依赖
- 依赖添加规范: 在coder-course-web/pom.xml中添加业务模块依赖，确保Spring Boot能扫描到所有Controller
- 示例依赖配置:
```

<dependency>
    <groupId>org.leocoder.course</groupId>
    <artifactId>coder-course-education</artifactId>
    <version>${revision}</version>
</dependency>
```
- 验证方法: 添加依赖后重新编译和启动应用程序，确保所有Controller接口能正常访问

13 KiB Raw Blame History Unescape Escape