weixin_uniapp_1818AIGC/docs/CODE_STANDARDS.md

代码开发规范

一、项目结构规范

src/main/java/com/dora/
├── WeixinApplication.java      # 启动类
├── common/                     # 公共模块
│   ├── constant/              # 常量定义
│   ├── enums/                 # 枚举类
│   ├── exception/             # 异常处理
│   └── result/                # 统一响应
├── config/                     # 配置类
├── controller/                 # 控制器层（接收请求）
├── service/                    # 业务服务层
│   └── impl/                  # 服务实现
├── mapper/                     # 数据访问层
├── entity/                     # 数据库实体
├── dto/                        # 数据传输对象（入参）
├── vo/                         # 视图对象（出参）
├── util/                       # 工具类
└── aspect/                     # 切面

二、命名规范

2.1 类命名

类型	规范	示例
Controller	XxxController	UserController
Service接口	XxxService	UserService
Service实现	XxxServiceImpl	UserServiceImpl
Mapper	XxxMapper	UserMapper
Entity	与表名对应，驼峰	User, AiWork
DTO	XxxDTO / XxxRequest	UserLoginDTO
VO	XxxVO	UserInfoVO
枚举	XxxEnum	UserStatusEnum
常量	XxxConstant	RedisConstant
工具类	XxxUtil	DateUtil
配置类	XxxConfig	RedisConfig

2.2 方法命名

操作	命名规范	示例
查询单个	getXxx / findXxx	getUserById
查询列表	listXxx	listUserByStatus
分页查询	pageXxx	pageUser
新增	save / add / create	saveUser
修改	update / modify	updateUser
删除	delete / remove	deleteUser
统计	countXxx	countUserByVip
判断	isXxx / hasXxx	isVipUser

2.3 变量命名

• 使用小驼峰：userId, orderNo
• 布尔类型：isXxx, hasXxx, canXxx
• 集合类型：复数形式 users, orderList
• 常量：全大写下划线分隔 MAX_RETRY_COUNT

三、Controller规范

@Slf4j
@RestController
@RequestMapping("/user")
@RequiredArgsConstructor
public class UserController {

    private final UserService userService;

    /**
     * 获取用户信息
     *
     * @param id 用户ID
     * @return 用户信息
     */
    @GetMapping("/{id}")
    public Result<UserVO> getById(@PathVariable Long id) {
        return Result.success(userService.getById(id));
    }

    /**
     * 分页查询用户
     */
    @GetMapping("/page")
    public Result<IPage<UserVO>> page(UserPageDTO dto) {
        return Result.success(userService.page(dto));
    }

    /**
     * 新增用户
     */
    @PostMapping
    public Result<Long> save(@RequestBody @Valid UserSaveDTO dto) {
        return Result.success(userService.save(dto));
    }

    /**
     * 更新用户
     */
    @PutMapping("/{id}")
    public Result<Void> update(@PathVariable Long id, @RequestBody @Valid UserUpdateDTO dto) {
        userService.update(id, dto);
        return Result.success();
    }

    /**
     * 删除用户
     */
    @DeleteMapping("/{id}")
    public Result<Void> delete(@PathVariable Long id) {
        userService.delete(id);
        return Result.success();
    }
}

Controller规则

1. 使用 @RequiredArgsConstructor 构造器注入，禁止 @Autowired
2. 方法必须有注释说明
3. 入参使用 DTO，出参使用 VO
4. 参数校验使用 @Valid
5. 统一返回 Result<T>
6. 不写业务逻辑，只做参数接收和结果返回

四、Service规范

public interface UserService {
    
    UserVO getById(Long id);
    
    IPage<UserVO> page(UserPageDTO dto);
    
    Long save(UserSaveDTO dto);
    
    void update(Long id, UserUpdateDTO dto);
    
    void delete(Long id);
}

@Slf4j
@Service
@RequiredArgsConstructor
public class UserServiceImpl implements UserService {

    private final UserMapper userMapper;
    private final RedisUtil redisUtil;

    @Override
    public UserVO getById(Long id) {
        User user = userMapper.selectById(id);
        if (user == null) {
            throw new BusinessException(ResultCode.USER_NOT_FOUND);
        }
        return convertToVO(user);
    }

    @Override
    @Transactional(rollbackFor = Exception.class)
    public Long save(UserSaveDTO dto) {
        // 1. 参数校验
        checkPhoneExists(dto.getPhone());
        
        // 2. 构建实体
        User user = new User();
        BeanUtils.copyProperties(dto, user);
        
        // 3. 保存数据
        userMapper.insert(user);
        
        // 4. 返回结果
        return user.getId();
    }
}

Service规则

1. 接口与实现分离
2. 事务注解加在实现类方法上：@Transactional(rollbackFor = Exception.class)
3. 复杂业务逻辑拆分为私有方法
4. 异常使用 BusinessException 抛出
5. 日志记录关键操作

五、Entity规范

@Data
@TableName("user")
public class User {

    @TableId(type = IdType.AUTO)
    private Long id;

    private String openid;

    private String nickname;

    private String phone;

    private Integer vipLevel;

    private LocalDateTime vipExpireTime;

    private Integer points;

    private Integer status;

    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createdAt;

    @TableField(fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime updatedAt;

    @TableLogic
    private Integer deleted;
}

Entity规则

1. 使用 @Data 简化代码
2. 字段类型与数据库对应
3. 时间类型使用 LocalDateTime
4. 逻辑删除字段使用 @TableLogic
5. 禁止在Entity中写业务方法

六、DTO/VO规范

// 入参DTO
@Data
public class UserSaveDTO {

    @NotBlank(message = "手机号不能为空")
    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
    private String phone;

    @NotBlank(message = "昵称不能为空")
    @Size(max = 64, message = "昵称最长64个字符")
    private String nickname;
}

// 出参VO
@Data
public class UserVO {

    private Long id;

    private String nickname;

    private String avatar;

    private Integer vipLevel;

    private String vipLevelName;

    private Integer points;

    private LocalDateTime createdAt;
}

DTO/VO规则

1. DTO用于接收入参，必须加校验注解
2. VO用于返回数据，可添加格式化字段
3. 禁止直接返回Entity
4. 敏感字段（密码、token）不放入VO

七、Mapper规范

@Mapper
public interface UserMapper extends BaseMapper<User> {

    /**
     * 根据手机号查询用户
     */
    User selectByPhone(@Param("phone") String phone);

    /**
     * 批量更新状态
     */
    int batchUpdateStatus(@Param("ids") List<Long> ids, @Param("status") Integer status);
}

Mapper规则

1. 继承 BaseMapper<T> 使用通用方法
2. 复杂SQL写在XML文件中
3. 参数使用 @Param 注解
4. 禁止在Mapper中写业务逻辑

八、异常处理规范

// 抛出业务异常
throw new BusinessException(ResultCode.USER_NOT_FOUND);
throw new BusinessException("自定义错误信息");
throw new BusinessException(4001, "自定义错误码和信息");

// 参数校验
if (user == null) {
    throw new BusinessException(ResultCode.USER_NOT_FOUND);
}

// 使用断言（推荐）
Assert.notNull(user, "用户不存在");

九、日志规范

@Slf4j
public class UserServiceImpl {

    public void doSomething() {
        // DEBUG：调试信息
        log.debug("查询用户参数: {}", dto);
        
        // INFO：关键业务操作
        log.info("用户注册成功, userId={}, phone={}", user.getId(), user.getPhone());
        
        // WARN：警告信息
        log.warn("用户登录失败次数过多, userId={}", userId);
        
        // ERROR：异常错误（带异常堆栈）
        log.error("调用第三方接口失败, url={}", url, e);
    }
}

日志规则

1. 使用 @Slf4j 注解
2. 使用占位符 {}，禁止字符串拼接
3. ERROR日志必须带异常对象
4. 敏感信息脱敏处理

十、数据库规范

10.1 连接池配置

项目使用 HikariCP 连接池，已优化配置：

• 最小空闲连接：10
• 最大连接数：50
• 空闲超时：10分钟
• 连接最大存活：30分钟
• 泄漏检测：60秒

10.2 SQL规范

1. 禁止 SELECT *，明确指定字段
2. 大表查询必须走索引
3. 禁止在循环中执行SQL
4. 批量操作使用 saveBatch
5. 分页查询必须有排序字段

// 错误示例
for (Long id : ids) {
    userMapper.selectById(id);  // N+1问题
}

// 正确示例
List<User> users = userMapper.selectBatchIds(ids);

10.3 事务规范

// 只读事务
@Transactional(readOnly = true)
public UserVO getById(Long id) { }

// 写事务
@Transactional(rollbackFor = Exception.class)
public void save(UserDTO dto) { }

十一、接口规范

11.1 RESTful规范

操作	方法	路径	示例
查询	GET	/资源	GET /users
详情	GET	/资源/{id}	GET /users/1
新增	POST	/资源	POST /users
修改	PUT	/资源/{id}	PUT /users/1
删除	DELETE	/资源/{id}	DELETE /users/1

11.2 响应格式

{
    "code": 200,
    "message": "操作成功",
    "data": {},
    "timestamp": 1704067200000
}

十二、安全规范

1. 敏感配置使用环境变量或配置中心
2. 密码使用 BCrypt 加密存储
3. 接口做权限校验
4. 防止SQL注入，使用参数化查询
5. 防止XSS，对输出内容转义
6. 日志脱敏处理敏感信息

十三、Git提交规范

<type>(<scope>): <subject>

feat: 新功能
fix: 修复bug
docs: 文档更新
style: 代码格式
refactor: 重构
test: 测试
chore: 构建/工具

示例：

feat(user): 添加用户注册功能
fix(order): 修复订单金额计算错误
docs(readme): 更新部署文档