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或其他测试框架进行单元测试。
对每个业务功能编写相应的测试用例。

总结

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

bijw@yiqisoft.cn 发布的文章

Spring boot项目的开发标准和代码规范

目录

前言

命名规范

入参校验

数据库交互

标准的注释

API文档

异常处理

异常返回信息

日志和监控

测试

总结

最新文章

分类