ChronicDisease_SpringBoot/docs/DevRule/01-代码风格指南.md

01-代码风格指南

1. 命名规范

1.1 包名

• 包名全部使用小写字母，使用点号分隔单词。
• 示例：work.baiyun.chronicdiseaseapp

1.2 类名和接口名

• 使用驼峰命名法（CamelCase），首字母大写。
• 示例：SpringAPP、WeChatController、UserService

1.3 方法名

• 使用驼峰命名法（camelCase），首字母小写。
• 示例：getOpenid、generateToken、addInterceptors

1.4 变量名和字段名

• 使用驼峰命名法（camelCase），首字母小写。
• 示例：weChatService、username、authInterceptor

1.5 常量名

• 全部大写，使用下划线分隔单词。
• 示例：TOKEN_TTL_HOURS、REFRESH_THRESHOLD_HOURS

1.6 枚举值

• 全部大写，使用下划线分隔单词。
• 示例：MALE、FEMALE

2. 代码格式

2.1 缩进

• 使用4个空格进行缩进，不使用制表符（Tab）。

2.2 花括号

• 类和方法的花括号在声明行的末尾。

• 示例：

  public class Example {
    public void method() {
        // code
    }
  }
  

2.3 导入语句

• 导入语句按以下顺序分组：
  1. Java标准库（java.*）
  2. 第三方库（com.*、org.*等）
  3. 项目内部包（work.baiyun.*）
• 组间用空行分隔。

2.4 行长度

• 单行代码不超过120个字符，超出时适当换行。

2.5 空格

• 运算符前后加空格，如 a + b。
• 方法参数之间用逗号加空格分隔，如 method(a, b, c)。
• 控制语句关键字后加空格，如 if (condition)。

3. 注释规范

3.1 类注释

• 使用Javadoc注释 /** */。

• 示例：

  /**
  * 性别枚举，数据库存储为整数：1=男, 2=女
  */
  public enum Gender {
  

3.2 方法注释

• 公共方法使用Javadoc注释。

• 示例：

  /**
  * 获取用户OpenID
  */
  public R<?> getOpenid(GetOpenidRequest req) {
  

3.3 字段注释

• 使用 /** */ 注释字段，描述字段含义。

• 示例：

  /** 用户名;用户名 */
  @Schema(description = "用户名（可选）")
  private String username;
  

3.4 代码内注释

• 使用 // 进行单行注释，解释复杂逻辑。

• 示例：

  // role is required now
  if (req.getRole() == null) {
  

4. 其他约定

4.1 访问修饰符

• 字段使用 private。
• 方法根据需要使用 public、private 或 protected。

4.2 构造函数

• 使用 @Autowired 注解进行依赖注入。

• 示例：

  @Autowired
  public WebMvcConfig(AuthInterceptor authInterceptor) {
    this.authInterceptor = authInterceptor;
  }
  

4.3 异常处理

• 自定义异常继承 Exception。

• 示例：

  public class CustomException extends Exception {
    public CustomException(String message) {
        super(message);
    }
  }
  

4.4 常量定义

• 常量使用 public static final 修饰。

• 示例：

  public static final long TOKEN_TTL_HOURS = 72L;
  

4.5 枚举定义

• 使用 @EnumValue 注解指定数据库存储值。
• 提供 getCode()、getDescription() 等方法。

• 示例：

  public enum Gender {
    MALE(1, "男"),
    FEMALE(2, "女");
  
    @EnumValue
    private final int code;
    private final String description;
  
    // constructor and methods
  }