通过 @ConfigurationProperties 统一管理共享库的配置项，并由客户端应用按 profile 自行定义属性值，既避免重复配置，又完全兼容 Spring Boot 的多 profile 机制与外部化配置优先级规则。
通过 `@configurationproperties` 统一管理共享库的配置项，并由客户端应用按 profile 自行定义属性值，既避免重复配置，又完全兼容 spring boot 的多 profile 机制与外部化配置优先级规则。
在构建可复用的 Spring Boot 共享库（Common Library）时，一个核心挑战是如何让库自身不绑定具体环境配置，同时又能灵活支持不同 profile（如 local、dev、qa）下的差异化参数（如服务 URL、数据库连接串）。直接在库中硬编码 @PropertySource 或依赖 spring.profiles.active 动态加载资源文件（如 library.config-${spring.profiles.active}.properties）存在明显缺陷：它耦合了配置加载逻辑、难以处理多 profile 激活场景（如 spring.profiles.active=dev,feature-x），且违反了“配置外置化”和“关注点分离”的最佳实践。
✅ 推荐方案：基于 @ConfigurationProperties 的声明式配置契约
共享库应仅定义清晰、类型安全的配置结构，不参与配置来源决策。客户端应用负责提供符合约定的属性值——这天然契合 Spring Boot 的配置优先级体系（application-{profile}.properties > application.properties > 环境变量等），并完美支持多 profile 合并。
1. 在共享库中定义配置类
@ConfigurationProperties(prefix = "drphil.library")
@ConfigurationPropertiesScan // 启用自动扫描（需在 client 的主配置类上添加 @EnableConfigurationProperties 或启用 spring-boot-starter-actuator）
public class DrPhilLibraryProperties {
private String accountUrl;
private String ourDbaccountJdbc;
// 必须提供标准 getter/setter
public String getAccountUrl() { return accountUrl; }
public void setAccountUrl(String accountUrl) { this.accountUrl = accountUrl; }
public String getOurDbaccountJdbc() { return ourDbaccountJdbc; }
public void setOurDbaccountJdbc(String ourDbaccountJdbc) { this.ourDbaccountJdbc = ourDbaccountJdbc; }
}
? 命名建议：使用唯一前缀（如 drphil.library）避免与客户端其他配置冲突；属性名采用 kebab-case（如 account-url），Java 字段保持 camelCase，Spring Boot 会自动映射。
2. 客户端应用按 profile 提供配置
在调用方项目的 src/main/resources/ 下，按需创建 profile-specific 配置文件：
# application-local.properties drphil.library.account-url=localhost:9999/wiremock/accounts drphil.library.our-dbaccount-jdbc=H2Db
# application-dev.properties drphil.library.account-url=https://dev.accounts.mycompany.com/ drphil.library.our-dbaccount-jdbc=jdbc:postgresql://db456.nonprod.db.mycompany.com/db15
# application-qa.properties drphil.library.account-url=https://qa.accounts.mycompany.com/ drphil.library.our-dbaccount-jdbc=jdbc:postgresql://db123.nonprod.db.mycompany.com/db16
✅ 优势：多 profile 激活（如 --spring.profiles.active=dev,feature-auth）时，Spring Boot 会自动合并所有匹配的 application-{profile}.properties，无需库内任何特殊逻辑。
3. 在服务中注入并使用配置
@Service
public class AccountManageService {
private final DrPhilLibraryProperties properties;
private final JdbcTemplate jdbcTemplate;
public AccountManageService(DrPhilLibraryProperties properties, JdbcTemplate jdbcTemplate) {
this.properties = properties;
this.jdbcTemplate = jdbcTemplate;
}
public boolean isPrincipalAuthorisedForAccount(Principal user, String account) {
Data data = getAccountInfo(properties.getAccountUrl(), account);
String sql = "SELECT COUNT(*) FROM accounts WHERE owner = ? AND id = ?";
Integer count = jdbcTemplate.queryForObject(sql, Integer.class, user.getName(), account);
return count != null && count > 0;
}
}
关键注意事项与最佳实践：
- ? 禁止在库中使用 @Value 注入配置：@Value 无法享受 @ConfigurationProperties 的松散绑定、类型转换、校验（@Valid + @NotBlank）、元数据生成（IDE 支持）等优势。
- ? 确保客户端启用配置扫描：若未使用 @SpringBootApplication（它默认启用 @ConfigurationPropertiesScan），需在主类上显式添加 @EnableConfigurationProperties(DrPhilLibraryProperties.class)。
- ? 支持嵌套对象与集合：@ConfigurationProperties 可自然表达复杂结构（如 List
endpoints, DatabaseConfig db），比扁平化 @Value 更可维护。 - ? 文档即契约：在库的 README 或 JavaDoc 中明确列出所有必需/可选属性及其含义、示例值和 profile 约定，例如：“drphil.library.account-url —— 目标账户服务基础地址，各环境必须在对应 application-{profile}.properties 中定义”。
此方式将配置权完全交还给业务应用，共享库保持轻量、无状态、可测试性强，真正实现“一次定义、处处复用”，是 Spring Boot 生态中被 Hibernate、Kafka、Redis 等官方 Starter 广泛验证的成熟模式。
