luoweijian
/
crm-backend-matt
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
17 Commits
1 Branch
0 Tags
403 MiB
Tree: f0f70c6137
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'f0f70c6137'
${ noResults }
crm-backend-matt/.qoder/repowiki/zh/content/配置指南/应用配置.md

303 lines
15 KiB
Raw Normal View History

first-commit
1 month ago
# 应用配置
<cite>
**本文引用的文件**
- [crm-app/src/main/resources/application.yml](file://crm-app/src/main/resources/application.yml)
- [crm-auth/src/main/resources/application.yml](file://crm-auth/src/main/resources/application.yml)
- [crm-app/src/main/java/com/crm/app/CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java)
- [crm-auth/src/main/java/com/crm/auth/AuthApplication.java](file://crm-auth/src/main/java/com/crm/auth/AuthApplication.java)
- [crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java](file://crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java)
- [crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java)
- [crm-file/src/main/java/com/crm/file/config/FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向应用配置，系统性说明多模块 Spring Boot 应用的 application.yml 结构与使用方式。内容涵盖：
- 服务端口、上下文路径等基础运行参数
- 多环境配置（dev/test/prod）与激活策略
- 日志级别设置与输出规范
- Spring Boot 基础配置要点
- 配置文件加载优先级与环境变量覆盖机制
- 配置分组管理与最佳实践
- 不同部署环境的配置模板建议
## 项目结构
本项目采用多模块结构，关键应用入口与配置分布如下：
- crm-app：主应用启动类与默认 application.yml
- crm-auth：认证模块，包含独立 application.yml 及安全相关配置
- crm-base：公共基础能力，提供若干配置属性类（定时任务、雪花算法等）
- crm-file：文件服务模块，提供文件存储相关配置属性类
```mermaid
graph TB
subgraph "应用模块"
A["crm-app<br/>启动类 + application.yml"]
B["crm-auth<br/>application.yml + 安全/权限配置"]
C["crm-base<br/>通用配置属性类"]
D["crm-file<br/>文件配置属性类"]
end
A --> C
B --> C
B --> D
```
图表来源
- [crm-app/src/main/java/com/crm/app/CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java)
- [crm-app/src/main/resources/application.yml](file://crm-app/src/main/resources/application.yml)
- [crm-auth/src/main/resources/application.yml](file://crm-auth/src/main/resources/application.yml)
- [crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java](file://crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java)
- [crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java)
- [crm-file/src/main/java/com/crm/file/config/FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)
章节来源
- [crm-app/src/main/resources/application.yml](file://crm-app/src/main/resources/application.yml)
- [crm-auth/src/main/resources/application.yml](file://crm-auth/src/main/resources/application.yml)
- [crm-app/src/main/java/com/crm/app/CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java)
- [crm-auth/src/main/java/com/crm/auth/AuthApplication.java](file://crm-auth/src/main/java/com/crm/auth/AuthApplication.java)
## 核心组件
- 应用启动类
- crm-app 的启动类负责引导整个应用上下文，读取 application.yml 并装配各模块 Bean。
- crm-auth 的启动类用于认证服务的独立运行或集成场景。
- 配置属性类
- ScheduledTaskProperties：封装定时任务相关开关、调度表达式等。
- SnowflakeProperties：封装分布式 ID 生成器相关参数。
- FileProperties：封装文件上传、存储后端（如 MinIO）等参数。
- 配置文件
- 每个模块均提供 application.yml，作为该模块运行时配置的主要来源。
章节来源
- [crm-app/src/main/java/com/crm/app/CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java)
- [crm-auth/src/main/java/com/crm/auth/AuthApplication.java](file://crm-auth/src/main/java/com/crm/auth/AuthApplication.java)
- [crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java](file://crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java)
- [crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java)
- [crm-file/src/main/java/com/crm/file/config/FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)
## 架构总览
下图展示应用启动时配置加载与模块装配的总体流程，体现 application.yml 与各配置属性类的关系。
```mermaid
sequenceDiagram
participant JVM as "JVM"
participant App as "应用启动类"
participant Env as "环境变量/命令行参数"
participant Config as "Spring 配置源(application.yml)"
participant Props as "配置属性类(@ConfigurationProperties)"
participant Beans as "业务Bean"
JVM->>App : 启动主方法
App->>Env : 读取系统环境变量与启动参数
App->>Config : 加载 application.yml
Config-->>Props : 绑定到 @ConfigurationProperties
Props-->>Beans : 注入到各模块 Bean
Beans-->>App : 完成初始化
```
图表来源
- [crm-app/src/main/java/com/crm/app/CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java)
- [crm-auth/src/main/java/com/crm/auth/AuthApplication.java](file://crm-auth/src/main/java/com/crm/auth/AuthApplication.java)
- [crm-app/src/main/resources/application.yml](file://crm-app/src/main/resources/application.yml)
- [crm-auth/src/main/resources/application.yml](file://crm-auth/src/main/resources/application.yml)
- [crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java](file://crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java)
- [crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java)
- [crm-file/src/main/java/com/crm/file/config/FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)
## 详细组件分析
### 服务端口与上下文路径
- 常见配置项
- server.port：服务监听端口
- server.servlet.context-path：应用上下文路径前缀
- 使用建议
- 在 application.yml 中统一声明默认值
- 通过环境变量或启动参数覆盖，便于容器化部署
- 验证方式
- 启动后访问 http://host:port/context-path/actuator/health（若启用 Actuator）
章节来源
- [crm-app/src/main/resources/application.yml](file://crm-app/src/main/resources/application.yml)
- [crm-auth/src/main/resources/application.yml](file://crm-auth/src/main/resources/application.yml)
### 多环境配置（dev/test/prod）
- 激活方式
- spring.profiles.active：指定当前生效的环境 profile
- 文件组织
- 可为不同环境提供 application-dev.yml、application-test.yml、application-prod.yml
- 也可在同一 application.yml 中使用 spring.profiles 分组键
- 覆盖顺序
- 默认配置 < 环境特定配置 < 外部覆盖（环境变量/命令行）
章节来源
- [crm-app/src/main/resources/application.yml](file://crm-app/src/main/resources/application.yml)
- [crm-auth/src/main/resources/application.yml](file://crm-auth/src/main/resources/application.yml)
### 日志级别设置
- 常用配置项
- logging.level.root：根日志级别
- logging.level.com.crm.*：按包名细化日志级别
- logging.file.name / logging.file.path：日志文件输出位置
- 建议
- dev 环境开启 DEBUG，test 使用 INFO，prod 使用 WARN/ERROR 并配合审计
- 生产环境建议集中收集日志（如 ELK），避免本地磁盘写入瓶颈
章节来源
- [crm-app/src/main/resources/application.yml](file://crm-app/src/main/resources/application.yml)
- [crm-auth/src/main/resources/application.yml](file://crm-auth/src/main/resources/application.yml)
### Spring Boot 基础配置
- 数据源与缓存
- 数据库连接、连接池、Redis 连接等通常由各自模块配置类管理
- Web 与安全
- CORS、序列化、安全过滤器链等由对应配置类装配
- 建议
- 将敏感信息（密码、密钥）放入环境变量或配置中心，不在仓库中明文提交
章节来源
- [crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java](file://crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java)
- [crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java)
- [crm-file/src/main/java/com/crm/file/config/FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)
### 配置属性类与分组管理
- 推荐模式
- 使用 @ConfigurationProperties 将 application.yml 中的键映射为强类型对象
- 通过 prefix 进行配置分组，提高可读性与可维护性
- 示例分组
- app.scheduled-task.*：定时任务相关
- app.snowflake.*：分布式 ID 生成器
- file.storage.*：文件存储相关
章节来源
- [crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java](file://crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java)
- [crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java)
- [crm-file/src/main/java/com/crm/file/config/FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)
### 配置文件加载优先级与环境变量覆盖
- 加载优先级（从高到低）
- 命令行参数 --key=value
- Java 系统属性 -Dkey=value
- 操作系统环境变量
- application-{profile}.yml
- application.yml
- 覆盖机制
- 高优先级会覆盖低优先级同名键
- 支持嵌套键映射，例如 app.scheduled-task.enabled=true
- 最佳实践
- 默认值放在 application.yml
- 环境差异放在 application-{profile}.yml
- 敏感与动态值通过环境变量注入
章节来源
- [crm-app/src/main/resources/application.yml](file://crm-app/src/main/resources/application.yml)
- [crm-auth/src/main/resources/application.yml](file://crm-auth/src/main/resources/application.yml)
### 不同部署环境的配置模板建议
- 开发环境（dev）
- 端口：本地可用端口
- 上下文路径：/ 或 /api
- 日志：DEBUG，控制台+文件
- 数据源：本地 MySQL/Redis
- 第三方：Mock 或沙箱
- 测试环境（test）
- 端口：容器内固定端口
- 上下文路径：/api
- 日志：INFO，集中收集
- 数据源：测试库
- 第三方：测试账号/白名单
- 生产环境（prod）
- 端口：对外暴露端口
- 上下文路径：/api
- 日志：WARN/ERROR，集中收集
- 数据源：主从/分库分表、连接池优化
- 第三方：生产密钥、限流熔断
[本节为概念性指导，不直接分析具体文件]
## 依赖分析
- 模块间依赖
- crm-app 与 crm-auth 依赖 crm-base 提供的通用配置与工具
- crm-file 依赖 crm-base 的基础能力
- 配置依赖
- 各模块 application.yml 通过 @ConfigurationProperties 绑定到相应属性类
- 环境变量与 profile 决定最终生效的配置
```mermaid
graph LR
Base["crm-base<br/>配置属性类"] --> App["crm-app<br/>application.yml"]
Base --> Auth["crm-auth<br/>application.yml"]
Base --> FileMod["crm-file<br/>FileProperties"]
App --> |启动装配| Beans["业务Bean"]
Auth --> |启动装配| Beans
```
图表来源
- [crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java](file://crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java)
- [crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java)
- [crm-file/src/main/java/com/crm/file/config/FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)
- [crm-app/src/main/resources/application.yml](file://crm-app/src/main/resources/application.yml)
- [crm-auth/src/main/resources/application.yml](file://crm-auth/src/main/resources/application.yml)
章节来源
- [crm-app/src/main/resources/application.yml](file://crm-app/src/main/resources/application.yml)
- [crm-auth/src/main/resources/application.yml](file://crm-auth/src/main/resources/application.yml)
- [crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java](file://crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java)
- [crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java)
- [crm-file/src/main/java/com/crm/file/config/FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)
## 性能考虑
- 连接池与线程池
- 合理设置数据库连接池大小、超时时间
- 根据 CPU/内存调整 Tomcat 线程数与队列长度
- 日志与 I/O
- 生产环境减少同步写盘频率，使用异步日志
- 控制日志级别，避免高频 DEBUG 造成 IO 压力
- 缓存与中间件
- Redis 连接池、序列化策略需结合热点数据特征调优
[本节为通用指导，不直接分析具体文件]
## 故障排查指南
- 常见问题
- 端口冲突：检查 server.port 是否被占用
- 上下文路径错误：确认 server.servlet.context-path 与实际网关路由一致
- 环境变量未生效：核对命名规范与覆盖优先级
- 日志无输出：检查 logging.file.path 权限与磁盘空间
- 定位步骤
- 打印生效的 Profile 与配置源
- 使用 actuator 查看健康与指标
- 逐步降低日志级别定位问题
章节来源
- [crm-app/src/main/resources/application.yml](file://crm-app/src/main/resources/application.yml)
- [crm-auth/src/main/resources/application.yml](file://crm-auth/src/main/resources/application.yml)
## 结论
通过统一的 application.yml 与 @ConfigurationProperties 的组合，本项目实现了清晰、可维护且易于扩展的配置体系。遵循“默认值在默认配置、差异在环境配置、敏感值在环境变量”的原则，可有效提升开发与运维效率，保障多环境稳定交付。
[本节为总结性内容，不直接分析具体文件]
## 附录
- 常用命令
- 指定环境：--spring.profiles.active=dev
- 覆盖端口：--server.port=8081
- 设置日志级别：--logging.level.com.crm=DEBUG
- 参考清单
- 端口与上下文路径
- 多环境与激活
- 日志级别与输出
- 数据源与缓存
- 安全与跨域
- 定时任务与分布式 ID
- 文件存储配置
[本节为补充信息，不直接分析具体文件]