application.yml 配置规范

配置入口与职责

Samples 的后端统一使用 src/main/resources/application.yml，按 YAML 多文档和 profile 分层。公共约定放在公共段，本地连接值放在 local，容器网络差异放在 docker；dev/stg/pet/prd 保留配置中心连接信息，业务配置由 Nacos 提供。

共享的模块版本由 Parent 管理，application.yml 只承载运行配置。地址和凭据使用环境变量 / 配置中心提供的值。

公共段与配置导入

以下是以 Service1 为例的配置骨架；完整字段以相应模块源码为准：

server:
  port: ${SERVER_PORT:6003}
spring:
  application:
    name: macula-samples-service1
  profiles:
    active: '@profile.active@'
    group:
      docker: local
  config:
    import:
      - optional:nacos:${spring.application.name}.yml?refreshEnabled=true
      - optional:nacos:${spring.application.name}-${spring.profiles.active}.yml?refreshEnabled=true
  cloud:
    nacos:
      server-addr: ${spring.config.nacos.server-addr}
      namespace: ${spring.config.nacos.namespace}
      username: ${spring.config.nacos.username}
      password: ${spring.config.nacos.password}
      discovery:
        namespace: ${spring.cloud.nacos.namespace}

@profile.active@ 由 Maven profile 在构建时替换；local/dev/stg/pet/prd 定义在 Samples Parent。运行时可通过 SPRING_PROFILES_ACTIVE 选择环境，完整容器使用 docker，并通过 profile group 叠加 local。

spring.config.nacos.* 是本项目供占位引用使用的配置名；spring.cloud.nacos.* 是传给 Nacos 组件的属性。应用名要与 Nacos Data ID、服务发现和 Feign 目标一致。

local 与 docker

---
spring:
  config:
    activate:
      on-profile: local
    nacos:
      server-addr: 127.0.0.1:${NACOS_SERVER_PORT:28848}
      namespace: ${NACOS_NAMESPACE:MACULA5}
      username: ${NACOS_USERNAME:nacos}
      password: ${NACOS_PASSWORD:nacos}
  security:
    oauth2:
      resourceserver:
        jwt:
          jwk-set-uri: http://127.0.0.1:6000/oauth2/jwks
---
spring:
  config:
    activate:
      on-profile: docker
    nacos:
      server-addr: ${NACOS_SERVER_ADDR:nacos:8848}
  security:
    oauth2:
      resourceserver:
        jwt:
          jwk-set-uri: http://macula-samples-gateway:6000/oauth2/jwks

docker 复用 local，只覆盖有差异的值。数据库和 Redis 同理：IDE 使用宿主机发布端口，容器使用 Compose 服务名及容器端口。共享环境在对应 profile 中提供 Nacos 连接，维护 ${spring.application.name}.yml 和 ${spring.application.name}-${spring.profiles.active}.yml 两层配置。

三类地址分别配置

Gateway 配套设置 introspection Client；BFF 配套设置 macula.cloud.app-key、secret-key。BFF、Service1、Basic、OpenAPI、Thirdparty 都要使用应用网关的 JWK；Parent、API 契约和前端不承载该资源服务器配置。

BFF 当前使用的环境变量形式为：

macula:
  cloud:
    endpoint: ${MACULA_CLOUD_GATEWAY_INTERNAL_URL:http://127.0.0.1:9000}
    app-key: ${MACULA_CLOUD_APP_KEY:${spring.application.name}}
    secret-key: ${MACULA_CLOUD_APP_SECRET:example}

这里的默认值供本地示例使用。实际部署应注入平台登记信息。内部 JVM 使用可达的内网地址；浏览器使用可公开访问的 IAM 地址，这两者由不同使用方解析。

Redis 与持久化

• Service1 等普通业务服务使用 spring.data.redis.*。
• Samples Gateway 的自定义 RedisConfiguration 使用 spring.redis.* 与 spring.redis.system.*，分别连接项目 Redis、Cloud System Redis；遵循它的绑定代码，不做统一前缀替换。
• 数据库连接使用 spring.datasource.*；Service1 的 SQL 迁移放在 db/migration/，由 Flyway 管理。

修改数据库时追加下一版本迁移，保留已执行迁移的内容与校验信息。部署和数据持久化步骤见打包部署。

.env 与前端配置的边界

deploy/.env 由部署脚本、Compose 和 Vite 读取，Java / Maven / IDE 不会自动读取。IDE 中要覆盖默认值时，在运行配置中设置对应环境变量。

Admin 的 .env 保存公共默认值，.env.<mode> 覆盖模式差异；当前 Vite 合并顺序为模块本地配置、仓库根目录的 deploy/.env、进程环境变量，后者覆盖前者。业务请求使用同源 /api，IAM 登录地址供浏览器直连。

后端的 *_INTERNAL_URL 不应直接作为浏览器地址。进入前端的 OAuth / demo 配置对浏览器可见，不用它保存服务端凭据。

日志与可观测性

可运行后端使用 Observability Starter。日志结构、采样率和 OTLP Metrics / Traces / Logs 的开关、endpoint 放在相应环境配置中；当前本地默认关闭网络导出。API 聚合、Parent 与 Admin 不引入该运行时配置。

源码参考：Samples 各模块的 application.yml、Gateway 的 RedisConfiguration、Parent 的 pom.xml 及 Admin 的 vite.config.js。本页记录各文件对应提交。

• ←上一篇
• 下一篇→