目录

前言

这篇博客文章全面地覆盖了Spring Boot项目开发中应遵循的各种标准和规范。

命名规范

  • 类名应使用驼峰命名法，且名词性。
  • 变量和方法名也应使用驼峰命名法。
  • 常量名应全大写，单词间用下划线分隔。

入参校验

  • 使用Spring的@Valid注解和JSR 303规范中定义的注解（如@NotNull, @Size, @Min等）进行入参校验。
public ResponseEntity<String> create(@Valid @RequestBody User user) {
  //...
}

数据库交互

  • 使用JPA或MyBatis进行数据库操作。
  • 不要在业务逻辑代码中硬编码SQL语句。
  • 尽量避免使用nativeQuery = true。

标准的注释

  • 方法注释

每个公开的方法应该有Javadoc风格的注释，描述方法的目的、参数、返回值和可能抛出的异常。

/**
 * 根据ID获取用户信息
 *
 * @param id 用户ID
 * @return 用户对象
 * @throws UserNotFoundException 如果用户未找到
 */
public User getUserById(Long id) throws UserNotFoundException {
  //...
}
  • 属性注释

类和成员变量应有简洁明了的注释。

/**
用户ID
**/
private Long id;
/**
用户名
**/
private String username;
  • 逻辑注释

代码中的复杂逻辑应当有相应的注释解释。

// 检查用户是否已经注册
if (userExists(username)) {
  //...
}

API文档

整合Spring OpenApi生成API文档

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

在application.yml中添加配置信息

springdoc:
  swagger-ui:
    # 自定义的文档界面访问路径。默认访问路径是/swagger-ui.html
    path: /springdoc/docs.html

    # 字符串类型，一共三个值来控制操作和标记的默认展开设置。它可以是“list”（仅展开标记）、“full”（展开标记和操作）或“none”（不展开任何内容）。
    docExpansion: none

    # 布尔值。控制“试用”请求的请求持续时间（毫秒）的显示。
    displayRequestDuration: true

    # 布尔值。控制供应商扩展（x-）字段和操作、参数和架构值的显示。
    showExtensions: true

    # 布尔值。控制参数的扩展名（pattern、maxLength、minLength、maximum、minminimum）字段和值的显示。
    showCommonExtensions: true

    # 布尔值。禁用swagger用户界面默认petstore url。（从v1.4.1开始提供）。
    disable-swagger-default-url: true

  api-docs:
    # enabled the /v3/api-docs endpoint
    enabled: true

    # 自定义的文档api元数据访问路径。默认访问路径是/v3/api-docs
    path: /springdoc/api-docs

    # 布尔值。在@Schema（名称name、标题title和说明description，三个属性）上启用属性解析程序。
    resolve-schema-properties: true

  # 布尔值。实现OpenApi规范的打印。
  writer-with-default-pretty-printer: true

并用Springdoc的注解添加必要的API文档注释。

  • @Tag
  • @Operation: 描述这个 API 的主要功能和详细信息。
  • @ApiResponses: 列出所有可能的 HTTP 响应状态和它们的含义。
  • @ApiImplicitParams: 定义了所有需要的请求参数，包括它们的名字、数据类型、是否必须等。
  • @Parameter
  • @Schema

异常处理

  • 使用@ControllerAdvice和@ExceptionHandler进行全局异常处理。
@ControllerAdvice
public class GlobalExceptionHandler {

  @ExceptionHandler(UserNotFoundException.class)
  public ResponseEntity<String> handleUserNotFoundException(UserNotFoundException e) {
    return ResponseEntity.status(HttpStatus.NOT_FOUND).body(e.getMessage());
  }
}

异常返回信息

  • 尽量返回标准的错误格式和HTTP状态码。
Copy code
{
  "code": 404,
  "message": "用户未找到"
}

日志和监控

  • 使用SLF4J和Logback进行日志记录。
public class LoggingController {

    private static final Logger logger = LoggerFactory.getLogger(LoggingController.class);

    @GetMapping("/log")
    public String logExample() {
        logger.info("This is an info message");
        logger.warn("This is a warn message");
        logger.error("This is an error message");

        try {
            // 某些可能会抛出异常的代码
            throw new IllegalArgumentException("参数不正确");
        } catch (Exception e) {
            logger.error("发生异常：", e);
        }

        return "Check the logs for the details.";
    }
}
  • 下面是一个简单的logback.xml：
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <root level="info">
        <appender-ref ref="STDOUT" />
    </root>
</configuration>

测试

  • 使用JUnit或其他测试框架进行单元测试。
  • 对每个业务功能编写相应的测试用例。

总结

在快速开发的同时，遵循一定的开发规范是非常重要的。通过完善的入参校验，规范的注释，以及合适的文档和异常处理机制，我们不仅能够提升代码质量，还能大大提高团队的开发效率。

标签: none

添加新评论