企业官网建设流程全解析

你有没有想过，一个 Spring Boot 项目从把 spring-boot-starter-web 拖进 pom.xml，到 Controller 能正常接收请求，中间到底发生了什么？我之前也没想过，直到我决定把自己项目代号叫"豆包"的那套公共 Web 能力封装成一个自定义 Spring Boot Starter 时，才不得不把 Starter Web 的自动配置机制整个翻了一遍。这篇文章就是这次翻家底的过程记录，也是"豆包"这个 Starter 从零到接入真实项目、再到配合监控的完整实现笔记。

文章核心不放在复述官方文档，而是回答几个我当初最困惑的问题：Starter Web 凭什么加一个依赖就什么都好了？自定义 Starter 的自动配置类该怎么写才不会被用户覆盖？为什么有时候依赖加了却不生效，日志里也找不到线索？以及，接上 Spring Boot Admin 之后，怎么让这套 Starter 里的组件真的可观测。适合已经会用 Spring Boot 写接口、但对 starter 机制还处于"知其然不知其所以然"的人，也适合想在团队内部沉淀一套 Web 公共能力的同学。

1. 为什么会有"豆包"这个 Starter 项目

1.1 每个新项目都要重写一遍的"公共配置"

我手头维护的微服务不算多，但也不算少。一开始每个项目都是标准流程：引 spring-boot-starter-web，写一个 Controller，跑起来，能通就交差。等服务的数量超过五个以后，恶心的事情就来了。每个服务都要配一套基本一样的东西：全局异常处理要做吧，不然前端拿到一堆 Spring 默认的 Whitelabel 错误页，根本没法解析；CORS 要配吧，前端跨域调试隔三差五找你；请求日志要打吧，不然出了问题连"这个接口到底有没有被调到"都查不了；统一响应体更是躲不掉，给第三方的接口尤其需要一个稳定的错误码格式。

这些东西我在第一个项目里写了一份，第二个项目 Ctrl+C、Ctrl+V，第三个项目继续复制。等到第五个项目，已经出现了三套不一样的异常处理写法：有人返回 code + message，有人直接 ResponseEntity 包一层，有人干脆让异常往外抛。我意识到，问题的本质不是"每个人写代码风格不同"，而是公共能力缺少一个统一载体。与其每次靠人肉同步，不如做成一个 Starter，让所有服务开箱即用。

1.2 豆包的设计原则：可开关、不覆盖、尽量无感

给这个项目起名"豆包"，纯粹是因为那阵子下午茶天天吃豆包，没别的含义，内部代号而已。但设计原则我很较真，定了三条，后面所有编码都围绕这三条展开。

第一，可开关。不是每个服务都需要 CORS，也不是每个服务都想让 Starter 接管异常处理。所以我给所有自动配置都加了开关属性，默认开启，但你能通过配置一键关掉。第二，不覆盖。这是最容易被忽视的一条。Starter 提供的 Bean 必须是"兜底"的，用户只要自己声明了同类型的 Bean，我的就必须退让。实现方式很简单，用 @ConditionalOnMissingBean，后面会展开。第三，尽量无感。接入方不应该被迫继承任何基类、实现任何接口，只需要加依赖和写几行配置。把复杂度全部关在自动配置内部。

1.3 Starter 的命名规范和模块划分

命名上有个约定俗成的坑要先说：以 spring-boot-starter 开头的 artifactId 是 Spring 官方的保留命名，官方文档明确说第三方不要用这个前缀。反向的xxx-spring-boot-starter才是社区惯例。所以豆包拆了两个 Maven 模块：一个叫doubao-spring-boot-autoconfigure，放所有自动配置代码；一个叫doubao-spring-boot-starter，是一个几乎空的聚合包，依赖前者。业务项目里只需要引doubao-spring-boot-starter，不用感知 autoconfigure 的存在。如果你只需要在自己的项目里用，不分模块也行，但分模块以后如果还想对外发布或者做内部制品库，会优雅很多。

2. Starter Web 的自动配置到底帮我们做了什么

2.1 Starter 只是依赖聚合器，干活的是 spring-boot-autoconfigure

先说一个很多人没搞清的事实：spring-boot-starter-web这个 jar 打开之后里面几乎没有任何 Java 代码，它就是一个超大号的 pom，把所有 Web 开发需要的依赖聚合在一起。这里面有 spring-webmvc、spring-web、spring-boot-starter-json（负责 Jackson 集成）、spring-boot-starter-tomcat（内嵌容器），以及 spring-boot-starter（核心，包含自动配置的基础支持）。真正把 Bean 装配起来的逻辑，都在spring-boot-autoconfigure这个包里。理解了这一点，你就明白为什么自定义 Starter 时，我的 autoconfigure 模块依赖里不需要写一堆 web 组件的坐标，直接依赖 starter-web 就够了。

2.2 自动配置的加载链路：从 imports 文件到条件注解

自动配置的入口是主类上的@SpringBootApplication，它组合了@EnableAutoConfiguration。Spring 启动时，AutoConfigurationImportSelector会去读META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports这个文件，把里面列出来的全类名逐个加载。

注意，Spring Boot 2.7 之前这个文件叫spring.factories，key 是org.springframework.boot.autoconfigure.EnableAutoConfiguration。2.7 之后换成了新的 imports 文件，自定义 Starter 时直接用新格式即可。

加载不等于生效。每个自动配置类上都有一堆条件注解，核心的几个：

• @ConditionalOnClass：类路径上必须存在指定类才加载。
• @ConditionalOnWebApplication：必须是 Web 应用（还能细分 SERVLET 还是 REACTIVE）。
• @ConditionalOnMissingBean：容器里不存在指定类型的 Bean 才生效。
• @ConditionalOnProperty：配置项满足条件才生效。

这套机制的价值在于"按需装配"：Tomcat 相关自动配置发现能找到 Servlet 类才创建 Web 容器；WebMvc 配置发现没有用户自定义的 ViewResolver 才注册默认的。这也是为什么你可以塞进去一个 Jetty 替换 Tomcat，或者自己定义一个 WebMvcConfigurer 而不被自动配置干扰。

2.3 几张关键"配置卡"逐一说清

我把 Starter Web 背后最关键的几个自动配置类列成一张表，方便对照：

网上一搜"Spring MVC 处理一次请求的完整流程"，大家总觉得很玄，其实拆开看就是：请求先被容器接收，转给 DispatcherServlet，DispatcherServlet 通过 HandlerMapping 找到 Controller 方法，再用 HandlerAdapter 调用，最后返回值经过 HttpMessageConverter 序列化回前端。线程、拦截器、过滤器都挂在链路的不同位置。自动配置干的事，就是把这些环节的默认实现按条件装配好，让你从写第一行 Controller 开始就直接在一条完整的链路上工作。

3. 豆包 Starter 的核心实现：自动配置类怎么写

3.1 工程拆分成 autoconfigure 与 starter 两个模块

豆包的根 POM 有两个模块。autoconfigure 模块的依赖大致是这样：

<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-autoconfigure</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <scope>provided</scope> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-configuration-processor</artifactId> <optional>true</optional> </dependency> </dependencies>

关键点有两个。一是 starter-web 用providedscope：我的代码编译期要引用 DispatcherServlet 这些类，但真正运行时由业务项目自己引入 web 依赖，避免我打包时把 Tomcat 和 webmvc 全塞进去，导致版本冲突。二是spring-boot-configuration-processor要加上，它会在编译时生成配置元数据，这样使用方在 application.yml 里写doubao.web.*时，IDE 会有字段提示和补全，体验完全不一样。

3.2 注册自动配置：AutoConfiguration.imports 的写法

在src/main/resources/META-INF/spring/下新建org.springframework.boot.autoconfigure.AutoConfiguration.imports，内容一行一个全类名：

com.example.doubao.autoconfigure.DoubaoWebAutoConfiguration

再强调一次，不要把这个文件放到META-INF/spring.factories里，那是 2.7 之前的旧格式。新格式的好处是加载顺序可以通过@AutoConfigureBefore、@AutoConfigureAfter来控制，比如我可以声明在 WebMvcAutoConfiguration 之后再加载，确保覆写行为符合预期。我的豆包没太依赖顺序，但如果你要处理自定义 Filter 和 Spring Security 的 FilterChain，这个就很关键了。

3.3 配置属性类：让使用者能按需开关

配置属性类用@ConfigurationProperties(prefix = "doubao.web")绑定，字段名的命名遵循松绑定规则，也就是 yml 里的cors-enabled能自动对应 Java 的corsEnabled。

@ConfigurationProperties(prefix = "doubao.web") public class DoubaoWebProperties { private boolean corsEnabled = true; private List<String> corsAllowedOrigins = new ArrayList<>(Arrays.asList("*")); private boolean globalExceptionEnabled = true; private boolean requestLogEnabled = true; private Integer maxRequestLogBodySize = 1024; // getters and setters ... }

这里有个经验：默认值尽量放在 Java 字段上，别放在配置里，否则你无法区分"用户没配"和"用户故意配了默认值"。默认开启，用户要关就写doubao.web.cors-enabled: false，语义清晰。

3.4 自动配置类与三件套组件的代码

自动配置类长这样：

@AutoConfiguration @ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET) @ConditionalOnClass(DispatcherServlet.class) @EnableConfigurationProperties(DoubaoWebProperties.class) public class DoubaoWebAutoConfiguration { @Bean @ConditionalOnMissingBean @ConditionalOnProperty(prefix = "doubao.web", name = "global-exception-enabled", havingValue = "true", matchIfMissing = true) public DoubaoGlobalExceptionHandler doubaoGlobalExceptionHandler() { return new DoubaoGlobalExceptionHandler(); } @Bean @ConditionalOnMissingBean @ConditionalOnProperty(prefix = "doubao.web", name = "cors-enabled", havingValue = "true", matchIfMissing = true) public WebMvcConfigurer doubaoCorsConfigurer(DoubaoWebProperties properties) { return new WebMvcConfigurer() { @Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping("/**") .allowedOrigins(properties.getCorsAllowedOrigins().toArray(new String[0])) .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS") .allowedHeaders("*") .allowCredentials(true); } }; } @Bean @ConditionalOnMissingBean @ConditionalOnProperty(prefix = "doubao.web", name = "request-log-enabled", havingValue = "true", matchIfMissing = true) public DoubaoRequestLogFilter doubaoRequestLogFilter(ObjectProvider<MeterRegistry> meterRegistryProvider) { return new DoubaoRequestLogFilter(meterRegistryProvider.getIfAvailable()); } }

这里有个细节值得单独说明：doubaoCorsConfigurer返回的是WebMvcConfigurer，不是CorsFilter。如果你用的是 Spring Security，这两个选择差别很大，后面踩坑部分专门讲。

全局异常处理的核心部分：

@RestControllerAdvice public class DoubaoGlobalExceptionHandler { private static final Logger log = LoggerFactory.getLogger(DoubaoGlobalExceptionHandler.class); @ExceptionHandler(BusinessException.class) public ResponseEntity<Map<String, Object>> handleBusinessException(BusinessException e) { Map<String, Object> body = new LinkedHashMap<>(); body.put("code", e.getCode()); body.put("message", e.getMessage()); return ResponseEntity.status(HttpStatus.OK).body(body); } @ExceptionHandler(Exception.class) public ResponseEntity<Map<String, Object>> handleException(Exception e, HttpServletRequest request) { log.error("Unhandled exception at {} {}", request.getMethod(), request.getRequestURI(), e); Map<String, Object> body = new LinkedHashMap<>(); body.put("code", 500); body.put("message", "系统繁忙，请稍后重试"); return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(body); } }

注意业务异常返回 200 但 code 非零，HTTP 状态码只管传输协议，业务码走 body，这是给第三方接口时最常见的约定。最后是请求日志过滤器，我让它顺便埋指标，为后面监控做准备。

public class DoubaoRequestLogFilter extends OncePerRequestFilter { private static final Logger log = LoggerFactory.getLogger(DoubaoRequestLogFilter.class); private final MeterRegistry meterRegistry; private final Counter requestCounter; private final Timer requestTimer; public DoubaoRequestLogFilter(MeterRegistry meterRegistry) { this.meterRegistry = meterRegistry; this.requestCounter = Counter.builder("doubao.web.requests") .description("total requests").register(meterRegistry); this.requestTimer = Timer.builder("doubao.web.request.latency") .description("request latency").register(meterRegistry); } @Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) throws ServletException, IOException { long start = System.currentTimeMillis(); try { chain.doFilter(request, response); } finally { long cost = System.currentTimeMillis() - start; log.info("{} {} cost={}ms status={}", request.getMethod(), request.getRequestURI(), cost, response.getStatus()); if (meterRegistry != null) { requestCounter.increment(); requestTimer.record(cost, TimeUnit.MILLISECONDS); } } } }

这里用OncePerRequestFilter而不是普通 Filter，因为它保证一次请求只过滤一次，避免转发时重复执行。MeterRegistry是 Micrometer 的核心接口，项目里只要引了 actuator，这个对象就会存在，没有也不影响主流程。

4. 把豆包 Starter 接进真实项目的完整流程

4.1 接入只需要两步：加依赖、写配置

以我之前做的一个商品服务为例。第一步，在业务项目的 pom.xml 里加依赖：

<dependency> <groupId>com.example</groupId> <artifactId>doubao-spring-boot-starter</artifactId> <version>1.0.0</version> </dependency>

第二步，在 application.yml 里按需配置。大部分情况甚至不用配，因为默认值已经够用：

server: port: 8080 doubao: web: cors-enabled: true cors-allowed-origins: - http://localhost:5173 - http://admin.example.internal request-log-enabled: true

如果你不想让某个接口被日志刷屏，或者前端不在白名单里，随时改配置就完事，代码一行不用动。这就是 Starter 的价值：接入成本极低，退出成本也极低。

4.2 用自动配置报告确认"豆包真的上了"

接入最怕的是"我以为生效了，其实没有"。有个很实用的办法，Spring Boot 自带一份自动配置评估报告。在 application.yml 里加一行：

debug: true

启动日志里会输出一个巨大的 CONDITIONS EVALUATION REPORT，里面每一行都标注了某个自动配置类或 Bean 是 matched 还是 did not match，以及匹配失败的条件是什么。搜DoubaoWebAutoConfiguration，能看到类似这样的输出：

DoubaoWebAutoConfiguration Matched conditional expressions (all individual conditions all matched): - @ConditionalOnClass found required class 'org.springframework.web.servlet.DispatcherServlet' - @ConditionalOnWebApplication (type = SERVLET) found standard servlet web application

如果显示 did not match，日志会告诉你具体是哪个条件没满足，比如类找不到、不是 Web 应用等。这是排查 Starter 失效的第一现场。线上环境不想开 debug 也没关系，actuator 的conditions端点可以看同样的内容，稍后监控章节会用到。

4.3 三个功能的实测走查

接入完成后，我按三条路径走查了一遍。

第一，异常处理。故意调一个不存在的接口/api/does-not-exist，按默认配置 Spring 会返回 404 白页。不过我的全局异常处理只管 Controller 抛出的异常，兜底 404 仍是 Spring 的 BasicErrorController。这里要注意：如果你希望 404 也返回统一 JSON，还需要额外配置，不能指望 Starter 全包。我用@ExceptionHandler(NoHandlerFoundException.class)补了一刀，并在自动配置里让静态资源映射为 false 时才走这个兜底，细节略过。

第二，CORS。前端跑在localhost:5173，直接 fetch 我的接口，浏览器 F12 里能看到响应头带上了Access-Control-Allow-Origin，预检请求 OPTIONS 也是 200。这就是配置里白名单生效的直接证据。

第三，请求日志。请求一次后日志里出现一行：

2025-06-12 15:03:22.123 INFO 11832 --- [nio-8080-exec-1] c.e.doubao.autoconfigure.log.DoubaoRequestLogFilter : GET /api/products cost=23ms status=200

至此，豆包的三件套才算真正在真实项目里落地。

5. 封装过程中踩过的坑：失效、覆盖、冲突的完整排查

5.1 症状一：依赖加了但完全没有生效

这个坑我印象最深。当时在另一个服务里加了豆包依赖，启动日志里根本搜不到 DoubaoWebAutoConfiguration。排查链路是这样的：

第一步，看 jar 是否真的进来了：mvn dependency:tree | grep doubao，发现依赖在。第二步，解压 jar 检查AutoConfiguration.imports文件是不是在META-INF/spring/下，发现文件丢了。问题出在 autoconfigure 模块的构建配置：那个文件被 maven-resources-plugin 的 filter 干扰，spring目录里的文件被当成了资源替换对象，内容里的包名被改掉，导致 imports 文件失效。这个问题的通用解法是在 pom 里对该目录关掉 resource filtering，或者直接检查 target 里的文件内容。

第三步，如果文件在，也搜不到，那就要怀疑@ConditionalOnClass(DispatcherServlet.class)没匹配上。我用的是 starter-web 的provided依赖，在 autoconfigure 模块编译没问题，但假如某个业务项目用 spring-boot-starter-webflux 取代了 web，那 DispatcherServlet 根本不在类路径上，条件自然不满足。这不是 bug，是设计。需要让 Starter 兼容响应式项目的话，得单独做一套 reactive 自动配置，工作量翻倍，豆包暂时只支持传统 Servlet 项目。

5.2 症状二：配置属性绑不上、IDE 也没有提示

有段时间豆包的cors-allowed-origins在 yml 里怎么写都不生效，后来发现是字段命名问题。我在属性类里写成了corsAllowedOrigins，yml 里配了cors-allowed-origin（少了个 s），松绑定规则下复数不匹配，值就丢了。这不是大坑，但很隐蔽：由于有默认值["*"]，你甚至感觉不到绑定失败，CORS 照样通，只是白名单没生效。

要避免这类问题，最有效的手段是启用 configuration-processor，并让 IDE 提示你"没有可绑定的属性"。如果没有提示，多半是元数据没生成或者前缀写错。另外，属性类上千万别忘了 getter 和 setter；Spring Boot 2.2 之后虽然支持构造器绑定，但普通 setter 绑定依然是默认路径，缺了 setter 就会静默失败。

5.3 症状三：CORS 和过滤器出现冲突

豆包最初用 Filter 方式实现 CORS，结果在带 Spring Security 的项目里翻车了：预检请求 OPTIONS 会被 Security 的登录过滤器拦下来，CORS 头永远加不上。这就是我前面说"为什么用 WebMvcConfigurer 而不是 CorsFilter"的原因。Spring Security 里正确姿势是三选一：去掉 Security 的项目用WebMvcConfigurer.addCorsMappings；带 Security 的项目在 SecurityFilterChain 里加http.cors()，并在 MVC 层保留映射；或者完全由 Security 接管，用CorsConfigurationSource配置。豆包的做法是只提供 MVC 层的映射，不碰 Security 的过滤器链，这样在普通项目里开箱即用，在 Security 项目里也不会产生拦截冲突。

如果你要在 Starter 里注册普通 Filter，还有一个顺序坑：@Order注解必须和FilterRegistrationBean的 setOrder 一致，或者干脆返回FilterRegistrationBean而不是 Filter，这样能精确控制它在过滤链中的位置。我吃过亏，Filter 顺序不对导致请求日志打出来的 URL 永远是最外层路径。

5.4 症状四：Starter 的默认 Bean 把用户的覆盖了

这是自定义 Starter 最容易犯的错。很多人图省事，在自动配置里直接写@Bean，不管三七二十一注册一个全局异常处理器，结果用户自己在项目里写的@RestControllerAdvice完全不生效，因为同类型 Bean 已经被 Starter 占了。Spring Boot 官方给出的最佳实践就是全局条件注解@ConditionalOnMissingBean：用户声明了，我的自动配置就让位；用户没声明，我才兜底。豆包三件套全部遵循这个原则。排查这类问题时，同样回到 CONDITIONS EVALUATION REPORT，看自己的 Bean 是 matched 还是 did not match，一目了然。

6. 监控补齐：豆包 Starter 与 Spring Boot Admin 的配合

6.1 可观测性的基础：Actuator 提供端点

Starter 只解决"能不能用"，上线之后还得解决"好不好用、有没有出问题"。Spring Boot 的常规做法是引入 actuator。在业务项目的 pom 里加上：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency>

然后配置端点暴露：

management: endpoints: web: exposure: include: health,metrics,conditions,info endpoint: health: show-details: always

conditions端点就是前文自动配置报告的 HTTP 版，线上排查 Starter 是否生效时非常有用。metrics端点能查到 Micrometer 收集的所有指标，包括豆包埋的doubao.web.requests和doubao.web.request.latency。现在你能回答"Spring Boot 实现监控都有哪些需求和功能"这个问题了：基础需求是健康检查和指标采集，进阶需求是告警和可视化，这两块靠 actuator 加一个展示端就能拼起来。

6.2 在豆包里加上自定义健康检查和指标

光有通用指标还不够，我让豆包还带了一个自定义健康指示器，用于检查依赖的 Redis 或数据库连通性。这里用最简形式示范：

@Component public class DoubaoHealthIndicator implements HealthIndicator { @Override public Health health() { boolean dependencyHealthy = checkDependency(); if (dependencyHealthy) { return Health.up().withDetail("doubao", "dependencies ok").build(); } return Health.down().withDetail("doubao", "dependency unavailable"); } private boolean checkDependency() { // 实际项目中在这里探测 Redis / 数据库 / 内部网关 return true; } }

/actuator/health的输出会多出一块doubao的状态。注意，HealthIndicator是 Spring Boot 自带的 SPI，Spring Boot Admin 会把所有 health 汇总显示，非常直观。指标侧，前面过滤器里已经用 Counter 和 Timer 做了请求量和耗时的埋点，这些数据不需要额外配置就能被metrics端点捞到，也可以被 Prometheus 拉走，属于 Micrometer 的标准套路。

6.3 Spring Boot Admin 监控端的搭建与接入

Spring Boot Admin 由一个独立的监控服务加被监控应用组成。如果只是自己调试，可以直接建一个 demo 工程作为服务端，依赖：

<dependency> <groupId>de.codecentric</groupId> <artifactId>spring-boot-admin-starter-server</artifactId> <version>3.2.3</version> </dependency>

主类上加@EnableAdminServer，服务端默认端口可以改成 8081：

server: port: 8081

被监控的商品服务作为客户端，加依赖和配置：

<dependency> <groupId>de.codecentric</groupId> <artifactId>spring-boot-admin-starter-client</artifactId> <version>3.2.3</version> </dependency>

spring: boot: admin: client: url: http://localhost:8081 instance: name: product-service

启动后，打开http://localhost:8081，就能在 Admin 面板里看到商品服务的在线状态、/actuator/health聚合结果、以及各项指标曲线。豆包的健康指示器、请求耗时指标都会直接出现在界面上，调试期排查问题效率提高不少。

6.4 上线前要看的几个关键指标与调优项

接入监控不是目的，能根据数据做判断才是。结合豆包和 Spring Boot Admin，我上线前固定看这几个指标：

填上常用的几个调优项：

server: port: 8080 tomcat: threads: max: 200 min-spare: 20 max-connections: 10000 accept-count: 200

有人喜欢一口气把线程池调得很大，实际经验是结合 P99 和 QPS 来调，线程数不是越大越好，太高反而上下文切换开销变大。豆包本身不做线程调优，它管的是应用层的公共能力，容器和 JVM 参数依然留给每个服务自己把控。

最后再分享一个体会。做完豆包这个 Starter，对我影响最大的不是省了多少行复制粘贴，而是被迫把"公共能力"的边界想清楚了：哪些东西可以抽象，哪些东西必须留给业务自己决定。开关要多，默认值要稳，条件注解要严谨。下一次你往自己团队里沉淀类似东西时，记住一条检验标准：接入方敢不敢在一个陌生项目里只用三行配置就把它用起来。敢，这个 Starter 就合格了。