personal-backend-coding-standard

后端编码规范技能

功能描述

提供后端开发的编码标准和最佳实践指导，帮助开发者编写高质量、可维护的后端代码。

何时使用

在以下情况调用此技能：

• 需要编写后端代码时
• 需要审查后端代码质量时
• 需要学习后端编码规范时
• 需要培训团队成员时

核心功能

• 命名规范：提供变量、方法、类的命名标准
• 代码结构：指导代码组织和文件结构
• 错误处理：规范异常处理和错误返回
• 数据库操作：提供数据库访问的最佳实践
• API设计：指导 RESTful API 的设计规范
• 安全规范：提供安全编码的最佳实践

输入参数

输出格式

{
  "status": "SUCCESS",
  "language": "Java",
  "framework": "Spring Boot",
  "focusArea": "naming",
  "rules": [
    {
      "category": "命名规范",
      "rules": [
        {
          "rule": "类名使用 PascalCase",
          "example": "class UserService",
          "description": "类名应采用大驼峰命名法"
        }
      ]
    }
  ],
  "bestPractices": ["最佳实践1", "最佳实践2"]
}

项目技术栈

项目模块结构

xx-parent/
├── xx-gateway/     # 网关模块 - 处理请求路由和认证
├── xx-biz/         # 业务模块 - 核心业务逻辑
└── xx-infra/       # 基础设施模块 - 公共组件、工具类

编码规范分类

1. 命名规范

2. 代码结构

src/main/java/com/bage/xx/
├── controller/          # REST API 控制层
│   └── UserController.java
├── service/             # 业务逻辑层
│   ├── UserService.java
│   └── impl/
│       └── UserServiceImpl.java
├── repository/          # 数据访问层
│   └── UserRepository.java
├── entity/              # 数据库实体
│   └── User.java
├── dto/                 # 数据传输对象
│   ├── request/
│   │   └── UserCreateRequest.java
│   └── response/
│       └── UserResponse.java
├── config/              # 配置类
│   └── WebConfig.java
├── exception/           # 自定义异常
│   ├── BusinessException.java
│   └── GlobalExceptionHandler.java
├── util/                # 工具类
│   └── StringUtils.java
└── Application.java     # 启动类

3. 方法设计

4. 日志规范

统一使用 Lombok @Slf4j 注解

import lombok.extern.slf4j.Slf4j;

@Slf4j
@Service
public class UserServiceImpl implements UserService {
    
    @Override
    public UserResponse createUser(UserCreateRequest request) {
        log.info("开始创建用户，邮箱: {}", request.getEmail());
        try {
            // 业务逻辑
            log.debug("用户创建成功，ID: {}", userId);
            return response;
        } catch (Exception e) {
            log.error("创建用户失败，邮箱: {}", request.getEmail(), e);
            throw e;
        }
    }
}

5. 错误处理

// 自定义异常
public class BusinessException extends RuntimeException {
    private final String errorCode;
    
    public BusinessException(String errorCode, String message) {
        super(message);
        this.errorCode = errorCode;
    }
}

// 全局异常处理
@RestControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<ErrorResponse> handleBusinessException(BusinessException e) {
        return ResponseEntity.badRequest()
            .body(new ErrorResponse(e.getErrorCode(), e.getMessage()));
    }
    
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleException(Exception e) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body(new ErrorResponse("INTERNAL_ERROR", "系统内部错误"));
    }
}

6. 数据库操作

7. API 设计

HTTP 方法限制：Controller 只暴露 GET 和 POST 请求，不使用 PUT、PATCH、DELETE 等其他方法

Controller 示例：

@RestController
@RequestMapping("/api/users")
public class UserController {
    
    @Autowired
    private UserService userService;
    
    // 查询 - 使用 GET
    @GetMapping("/{id}")
    public ResponseEntity<UserResponse> getUserById(@PathVariable String id) {
        return ResponseEntity.ok(userService.getUserById(id));
    }
    
    // 列表查询 - 使用 GET
    @GetMapping
    public ResponseEntity<List<UserResponse>> listUsers() {
        return ResponseEntity.ok(userService.listUsers());
    }
    
    // 创建 - 使用 POST
    @PostMapping
    public ResponseEntity<UserResponse> createUser(@RequestBody UserCreateRequest request) {
        return ResponseEntity.status(HttpStatus.CREATED)
            .body(userService.createUser(request));
    }
    
    // 更新 - 使用 POST（不使用 PUT/PATCH）
    @PostMapping("/{id}/update")
    public ResponseEntity<UserResponse> updateUser(
            @PathVariable String id, 
            @RequestBody UserUpdateRequest request) {
        return ResponseEntity.ok(userService.updateUser(id, request));
    }
    
    // 删除 - 使用 POST（不使用 DELETE）
    @PostMapping("/{id}/delete")
    public ResponseEntity<Void> deleteUser(@PathVariable String id) {
        userService.deleteUser(id);
        return ResponseEntity.noContent().build();
    }
}

8. 安全规范

最佳实践指南

Java 后端开发最佳实践

1. 使用 Lombok：简化样板代码，使用 @Slf4j、@Data、@Builder 等注解
2. 使用 DTO：分离实体和传输对象
3. 使用 Optional：避免空指针异常
4. 使用 Stream API：简化集合操作
5. 使用断言：验证方法参数
6. 编写单元测试：保证代码质量
7. 使用日志框架：使用 @Slf4j 注解（SLF4J + Logback）
8. 配置外部化：使用配置文件或环境变量

Spring Boot 最佳实践

@Slf4j
@Service
public class UserServiceImpl implements UserService {
    
    private final UserRepository userRepository;
    
    public UserServiceImpl(UserRepository userRepository) {
        this.userRepository = userRepository;
    }
    
    @Override
    @Transactional
    public UserResponse createUser(UserCreateRequest request) {
        log.info("创建用户请求: {}", request.getEmail());
        
        validateRequest(request);
        
        User user = User.builder()
            .email(request.getEmail())
            .name(request.getName())
            .build();
        
        User savedUser = userRepository.save(user);
        log.debug("用户创建成功，ID: {}", savedUser.getId());
        
        return UserResponse.fromEntity(savedUser);
    }
    
    private void validateRequest(UserCreateRequest request) {
        if (request.getEmail() == null || request.getEmail().isEmpty()) {
            throw new BusinessException("INVALID_PARAM", "邮箱不能为空");
        }
    }
}

代码审查检查清单

核心组件

配置要求

环境变量

Maven 依赖

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.0</version>
</parent>

<properties>
    <java.version>21</java.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

扩展指南

添加新的编码规则

1. 在规则引擎中添加新规则
2. 定义规则的检查逻辑
3. 更新代码审查检查清单

添加新语言支持

1. 创建对应语言的规则定义
2. 添加语言特定的最佳实践
3. 更新技能文档

触发条件