EFCv4.1.0-SNAPSHOT

外观

快速开始 ​

本例在已有 Spring Boot Web 应用中增加一个回显接口，验证响应包装、Long 序列化、TraceId、参数校验和业务异常。无需数据库、Store、登录用户 Provider 或 Business 模块。

准备 Java 25、Spring Boot 4.1.0，以及能够从本地或项目 Maven 仓库解析的 4.1.0-SNAPSHOT 构件。应用应已有启动类和可用的编译/启动插件；若尚未配置构建基线，先阅读Parent 与 BOM 的区别。本例沿用应用的构建和启动方式。

1. 添加 Base 依赖 ​

在应用 POM 中导入 Component BOM，再添加 Base。已有项目 BOM 或 Business BOM 管理相同版本时不重复导入。

xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.own</groupId>
            <artifactId>springboot-component-dependencies</artifactId>
            <version>4.1.0-SNAPSHOT</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>com.own.component</groupId>
        <artifactId>springboot-component-base</artifactId>
    </dependency>
</dependencies>

Base 已传递引入 Web、AspectJ 和 Validation。没有额外的 own.base.enabled 开关，BaseAutoConfiguration 随依赖自动加载；不要为本例开启全包扫描或重复注册默认异常处理器。

2. 添加演示 Controller ​

将下面类放在启动类的组件扫描范围内，按应用实际情况调整 package。本例只在 base-demo profile 下启用，避免演示错误接口混入正式业务入口。

java
package com.example.demo;

import com.own.component.base.model.R;
import com.own.component.base.model.ResultModel;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import org.springframework.context.annotation.Profile;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.time.LocalDateTime;

@Profile("base-demo")
@RestController
@RequestMapping("/base-demo")
public class BaseDemoController {

    @PostMapping("/echo")
    public ResultModel<EchoData> echo(@Valid @RequestBody EchoForm form) {
        return R.success(new EchoData(
                9007199254740993L, form.name(),
                LocalDateTime.of(2026, 9, 10, 10, 30, 0)));
    }

    @GetMapping("/failure")
    public ResultModel<String> failure() {
        return R.fail("演示业务失败");
    }

    public record EchoForm(@NotBlank(message = "名称不能为空") String name) {
    }

    public record EchoData(Long id, String name, LocalDateTime createdAt) {
    }
}

EchoData.id 特意使用包装类型 Long 和超过 JavaScript 安全整数范围的值，用于检查默认字符串输出。createdAt 是固定演示值，外层响应的 t 才是构造响应时的当前时间。

3. 启动并发送请求 ​

按应用原启动方式增加参数 --spring.profiles.active=base-demo；已有其他 profile 时同时保留。本例路径没有身份验证代码；若应用已启用认证拦截，按应用协议携带身份或在演示环境配置该路径的访问规则。

以本机端口 8080 为例，实际使用时替换端口及 context path：

sh
curl -i -X POST 'http://localhost:8080/base-demo/echo' \
  -H 'Content-Type: application/json' \
  -H 'trace-id: base-demo-001' \
  --data '{"name":"EFC"}'

默认配置下响应主体类似如下；t 随请求变化，字段顺序不作为协议约束：

json
{
  "code": "00000",
  "message": "请求成功",
  "t": "2026-09-10 10:30:00",
  "success": true,
  "traceId": "base-demo-001",
  "data": {
    "id": "9007199254740993",
    "name": "EFC",
    "createdAt": "2026-09-10 10:30:00"
  }
}

确认 data.id 为字符串、createdAt 使用空格分隔日期和时间，外层 traceId 与请求头相同。拦截器不主动添加 TraceId 响应头，应在响应主体中核对。

4. 验证失败分支 ​

继续发送以下请求：

sh
curl -i -X POST 'http://localhost:8080/base-demo/echo' \
  -H 'Content-Type: application/json' \
  --data '{"name":""}'

curl -i 'http://localhost:8080/base-demo/failure'
请求默认响应主体
空名称回显code=00003，message=名称不能为空，data 为错误消息列表；当前处理器仍保留 success=true
演示业务失败code=E0001、success=false，message 和 ex 为“演示业务失败”，没有 data 业务字段

这两个处理器都没有设置 HTTP 错误状态；普通已处理的 MVC 请求通常仍为 HTTP 200。客户端不能只判断 HTTP 状态或 success。校验错误码 00003 还与现有操作成功常量冲突，应用正式统一协议时需明确调整规则，见响应与异常。

省略 trace-id 或传入超过 36 字符的值时，组件会生成新的 UUID。若结果与示例不符，先检查应用是否覆盖了异常处理器或 JSON 转换器，再检查请求是否到达 MVC。

下一步 ​

示例涉及的源码类型

R、ResultModel。