Appearance

YAML 配置详解（基于 JavaFreeCloud2025 v2.0.1） ​

本章对 application.yml 及其导入的多个 YAML 配置文件（mysql.yml, jwt.yml, cache.yml, accesslog.yml, springdoc.yml）进行逐行深度解析。涵盖功能原理、参数含义、使用场景及生产环境调优建议。

一、主配置文件 application.yml ​

✅ 核心功能 ​

  • 定义应用基础属性（端口、名称）
  • 通过 spring.config.import 实现配置分离与模块化
  • 配置日志级别与文件输出
  • 设置文件上传限制

🔧 详细配置解析 ​

yaml
server:
  port: 8090

说明：应用监听的 HTTP 端口。

💡 建议：

  • 开发环境可使用默认值。
  • 生产环境应根据部署规划调整，并配合防火墙策略。
yaml
spring:
  application:
    name: javafree-cloud-demo

说明：应用名称，用于服务发现（如 Nacos）、日志标识和监控系统。

⚠️ 注意：在微服务架构中，此名称需全局唯一。

yaml
  config:
    import:
      - classpath:mysql.yml
      - classpath:jwt.yml
      - classpath:cache.yml
      - classpath:accesslog.yml
      - classpath:springdoc.yml

核心机制：配置导入（Spring Boot 2.4+ 新特性）

  • classpath: 表示从类路径加载资源。
  • 该机制替代了传统的 spring.profiles.include 或多 profile 文件方式，实现更清晰的配置分离。
  • 您可以将不同功能的配置拆分到独立文件，便于团队协作和维护。

✅ 优势：

  • 模块化清晰，避免单个文件过大。
  • 支持动态组合，例如在测试环境中不导入 accesslog.yml 以提升性能。
yaml
  servlet:
    multipart:
      max-file-size: 512MB
      max-request-size: 512MB
      enabled: true
      file-size-threshold: 0

文件上传配置：

参数说明
max-file-size单个文件最大大小
max-request-size整个请求体最大大小（支持多文件）
enabled是否启用文件上传
file-size-threshold文件超过此大小时写入磁盘，否则缓存在内存（0 表示始终写入磁盘）

🔐 安全建议：

  • 生产环境应根据业务需求设置合理上限，防止 DoS 攻击。
  • 对上传文件类型进行校验，并存储于非 Web 目录。
yaml
logging:
  level:
    ROOT: INFO
    cn.javafree.cloud: INFO
  file:
    name: javafree-springboot-demo.log

日志配置：

  • ROOT: 全局日志级别，INFO 是推荐的生产环境级别。
  • cn.javafree.cloud: 将框架日志设为 INFO，便于追踪框架行为。
  • name: 日志文件名，可使用绝对路径指定位置。

📈 进阶建议：

  • 使用 Logback 或 Log4j2 替代默认日志，支持滚动归档、异步日志等高级功能。
  • 在 Kubernetes 环境中，日志通常输出到 stdout/stderr，由日志收集器统一处理。
yaml
debug: false

调试模式：

  • 设为 true 时，Spring Boot 会输出更多自动配置报告（如哪些条件匹配/不匹配）。
  • 生产环境必须为 false，避免信息泄露和性能开销。

二、数据库配置 mysql.yml ​

✅ 核心功能 ​

  • 配置 Druid 数据源连接池
  • 启用 SQL 监控与防注入
  • 集成 JPA / Hibernate

🔧 详细配置解析 ​

yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/javafree2025-public?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai
    username: root
    password: root
    driver-class-name: com.mysql.cj.jdbc.Driver
    type: com.alibaba.druid.pool.DruidDataSource

数据源基础配置：

  • url 中的 serverTimezone=Asia/Shanghai 是关键，解决 MySQL 8+ 的时区问题。
  • 建议将 password 外部化，使用 ${DB_PASSWORD} 并通过环境变量或 KMS 注入。
yaml
    druid:
      initial-size: 5
      max-active: 10
      max-wait: 60000
      min-idle: 5

连接池核心参数：

参数推荐值说明
initial-size= min-idle启动时创建的连接数
max-active根据 QPS 调整最大连接数，过高会耗尽 DB 连接
max-wait30~60s获取连接超时时间，避免线程堆积
min-idlemax-active 的 50%~70%最小空闲连接，维持连接活性
yaml
      time-between-eviction-runs-millis: 60000
      min-evictable-idle-time-millis: 300000
      validation-query: SELECT 1
      test-while-idle: true

连接有效性校验：

  • test-while-idle: 在连接空闲时执行 validation-query 检查连接是否存活。
  • min-evictable-idle-time-millis: 连接空闲多久后可被回收。
  • 禁用 test-on-borrow 和 test-on-return，性能损耗大。
yaml
      filter:
        stat:
          enabled: true
          log-slow-sql: true
          slow-sql-millis: 2000
        wall:
          enabled: true
          config:
            delete-allow: true
            drop-table-allow: false
            case-condition-const-allow: true

Druid 内置监控与防火墙：

  • stat: 记录慢 SQL（>2s），用于性能分析。
  • wall: SQL 防火墙，禁止 DROP TABLE 等危险操作。
  • case-condition-const-allow: 允许 WHERE 1=1 类语句，避免误报。

🔒 生产建议：drop-table-allow: false 必须开启，防止误删表。

yaml
      web-stat-filter:
        enabled: true
        url-pattern: /* 
        exclusions: "*.js,*.gif,*.jpg,*.png,*.css,*.ico,/druid"
      stat-view-servlet:
        enabled: true
        url-pattern: /druid/*
        login-username: druid
        login-password: 123456

Druid 监控页面：

  • 访问 /druid 查看 SQL 执行情况、连接池状态。
  • 生产环境必须修改密码，并考虑 IP 白名单或反向代理保护。
yaml
  jpa:
    show-sql: true
    hibernate:
      ddl-auto: none
      naming:
        physical-strategy: org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl
    open-in-view: off

JPA 配置要点：

  • ddl-auto: none: 生产环境强制关闭，禁止自动建表。
  • open-in-view: off: 关闭延迟加载，避免 N+1 查询和连接占用。
  • naming.physical-strategy: 使用标准命名策略，避免字段名自动转下划线。

三、认证配置 jwt.yml ​

✅ 核心功能 ​

  • JWT 令牌生成与验证
  • 登录白名单管理
  • 刷新令牌机制

🔧 详细配置解析 ​

yaml
jwt:
  private.key: classpath:app.key
  public.key: classpath:app.pub
  private.key.password: "javafree-cloud-rsa-password"

密钥管理：

  • 使用 RSA 非对称加密，私钥签名，公钥验签。
  • classpath: 表示密钥在 resources/ 目录。
  • 生产环境建议使用外部密钥管理服务（KMS）。
yaml
  token.url: /auth/token
  refresh.token.url: /auth/refresh_token
  security:
    white_urls:
      - /
      - /login
      - /auth/token
      - /auth/refresh_token
      # ... (其他静态资源和 API 文档路径)

安全白名单：

  • 列出无需认证即可访问的 URL。
  • 包括登录接口、Swagger UI、静态资源等。
  • 注意路径顺序，通配符 /** 应放在最后。
yaml
    token:
      token_name: Javafreeauthorization
      token_head: "Bearer "
      issuer: javafree-cloud
      expiration: 7200
      refresh_expiration: 86400

JWT Token 配置：

参数说明
token_nameHTTP Header 名，避免与公司现有 JWT 冲突
token_headToken 前缀，标准格式为 Bearer <token>
issuer签发者，用于标识来源
expirationAccess Token 有效期（2小时）
refresh_expirationRefresh Token 有效期（1天）

四、缓存配置 cache.yml ​

✅ 核心功能 ​

  • Redis 单机/集群连接
  • Caffeine + Redis 多级缓存
  • Resilience4j 熔断保护

🔧 详细配置解析 ​

yaml
spring:
  data:
    redis:
      host: 127.0.0.1
      port: 6379
      password: 123456
      timeout: 2200ms
      lettuce:
        pool:
          max-active: 8
          max-idle: 4
          min-idle: 1
          max-wait: 5000ms

Redis 连接池配置：

  • timeout: 连接超时时间，建议 1~3 秒。
  • max-active: 根据 QPS 和平均响应时间估算。
  • min-idle: 生产环境建议 >=5，维持连接预热。
yaml
  cache:
    type: redis
    multilevel:
      enable-redis: true
      time-to-live: 30m
      use-key-prefix: true
      key-prefix: "JAVAFREENEWCACHEKEY:DEV"
      topic: "cache:multilevel:topic"
      allow-null-values: true

多级缓存配置：

  • key-prefix: 统一前缀，避免键冲突，建议包含项目名和环境。
  • allow-null-values: 防止缓存穿透，将空结果也缓存一段时间。
  • topic: Redis Pub/Sub 主题，用于集群环境下本地缓存失效同步。
yaml
      local:
        max-size: 2000
        initial-capacity: 1000
        expire-mode: RANDOM
        expiry-jitter: 50

Caffeine 本地缓存：

  • expire-mode: RANDOM: 随机过期时间，±50%，防止缓存雪崩。
  • max-size: 控制内存占用，避免 OOM。
yaml
      circuit-breaker:
        failure-rate-threshold: 35
        slow-call-duration-threshold: 500ms
        wait-duration-in-open-state: 30s

熔断器配置（Resilience4j）：

  • 当 Redis 响应缓慢或失败率高时，快速失败，保护下游服务。
  • 参数已根据生产经验调优，避免短暂抖动触发熔断。

五、日志配置 accesslog.yml ​

✅ 核心功能 ​

  • 请求日志记录（JPA / Elasticsearch）
  • 异步线程池处理
  • 自动清理旧日志

🔧 详细配置解析 ​

yaml
accesslog:
  enabled: true
  storage: jpa
  retention-minutes: 1440
  cleanup-enabled: true
  cleanup-cron: "0 0 */2 * * ?"

日志存储与清理：

  • storage: 可选 jpa（数据库）或 elasticsearch（高性能搜索）。
  • cleanup-cron: 每 2 小时清理一次过期日志。
  • retention-minutes: 日志保留 24 小时。
yaml
  cache-request-body: true
  max-body-size: 1048576

请求体缓存：

  • 为 POST/PUT 请求记录请求体，用于审计。
  • max-body-size: 限制缓存大小，避免内存溢出。
yaml
  thread-pool:
    core-size: 4
    max-size: 8
    queue-capacity: 1000

异步线程池：

  • 日志记录异步化，避免阻塞主请求。
  • 队列容量 1000，足够应对突发流量。

六、API 文档配置 springdoc.yml ​

✅ 核心功能 ​

  • OpenAPI 3 文档生成
  • Swagger UI 配置
  • 安全方案定义

🔧 详细配置解析 ​

yaml
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    enabled: true
  api-docs:
    path: /v3/api-docs
    enabled: true

基础配置：

  • api-docs: OpenAPI JSON 路径。
  • swagger-ui: UI 访问路径。
yaml
  packages-to-scan: cn.javafree
  paths-to-exclude:
    - /admin/**
    - /internal/**

扫描范围控制：

  • 仅扫描 cn.javafree 包下的 API。
  • 排除内部管理接口，不对外暴露。
yaml
javafree:
  springdoc:
    title: JavaFree Cloud API
    version: 2.0.1
    description: 由 javafree-cloud-springdoc生成
    contact:
      name: JavaFreeCloud 技术支持
      email: gwz126@126.com
    servers:
      - url: http://localhost:8090
        description: 开发环境
      - url: https://api.javafree.cn
        description: 生产环境
    jwt-security: true

自定义元信息：

  • 定义 API 标题、版本、联系人。
  • servers: 提供多环境切换选项。
  • jwt-security: true: 在 Swagger UI 中添加 Bearer Token 输入框。