配置约定

本页只讲三件事：配置键的前缀怎么定、自动配置怎么被 Spring Boot 发现、想改默认行为时从哪下手。各模块的具体配置项与默认值见配置参考，不在这里罗列。

配置前缀复制标题链接

自研能力统一使用 continew-starter 前缀，格式为 continew-starter.<module>[.<sub-feature>]，每个前缀常量定义在 continew-starter-core 的 PropertiesConstants 类中。

continew-starter:
  web:
    cors:
      enabled: true          # continew-starter.web.cors
  encrypt:
    field:
      enabled: true          # continew-starter.encrypt.field

这条约定只覆盖 Starter 自己定义的配置。对上游框架的扩展会沿用对方的命名空间，不要写成 continew-starter.*：

判断某个键该用哪个前缀，直接看它绑定的是哪个 @ConfigurationProperties 类；拿不准时查配置参考，它按前缀分组列出全部真实存在的键。

多数配置项都有合理默认值，引入模块后零配置即可用；只有默认关闭的能力（如跨域）或要改默认行为时才需要显式配置。

自动配置机制复制标题链接

每个 Starter 模块通过 Spring Boot 3 的 AutoConfiguration.imports 机制注册自动配置（不是旧版 spring.factories），文件位于各模块：

src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

引入依赖后自动配置即生效，无需手写 @Configuration。要排除某个自动配置，用 Spring Boot 的 spring.autoconfigure.exclude，填注册表中真实存在的类名，而不是想当然的模块名。以 Web 模块为例，AutoConfiguration.imports 里注册的是：

top.continew.starter.web.autoconfigure.mvc.WebMvcAutoConfiguration
top.continew.starter.web.autoconfigure.cors.CorsAutoConfiguration
top.continew.starter.web.autoconfigure.server.UndertowAutoConfiguration

spring:
  autoconfigure:
    exclude: top.continew.starter.web.autoconfigure.cors.CorsAutoConfiguration

排除前先确认目标类确实在该模块的 AutoConfiguration.imports 文件中；填了不存在的类名时 Spring Boot 会按无效排除处理，达不到禁用效果。

条件化装配复制标题链接

多数自动配置类带 @ConditionalOnProperty，只有设置了对应属性（通常是 enabled: true）才装配 Bean。默认开关因模块而异，例如 continew-starter.web.cors.enabled 默认 false、continew-starter.trace.enabled 默认 false、continew-starter.log.enabled 默认 true。是否默认启用以各模块文档与配置参考为准，不要凭经验推断。

覆盖默认 Bean复制标题链接

多数模块的关键 Bean 标注了 @ConditionalOnMissingBean，声明同类型 Bean 即可覆盖默认实现。

@Configuration
public class CustomConfig {

    @Bean
    public MyService myService() {
        // 将覆盖 Starter 的默认 Bean
        return new MyServiceImpl();
    }
}

少数模块按 Bean 名精确装配（例如部分缓存服务），此时需要按文档要求指定 Bean 名，只声明同类型 Bean 不会被注入。这类约束在各模块页中单独说明。

下一步复制标题链接

• 各模块的具体配置项见配置参考
• 各模块的能力与用法见功能模块