<!-- generated-by: gsd-doc-writer -->
# 配置参考

适用 Core `3.0.0-SNAPSHOT`，2026-09-19 对照源码。表中“默认”指字段初始值，应用 YAML、环境变量或自定义配置可能覆盖它。Core 是库，没有独立的生产地址或必填数据库凭据。

## 应用配置

来源：[ApplicationProperties](../../ineed-core-base/src/main/java/com/ineed/base/configuration/ApplicationProperties.java)，前缀 `application`。

| 配置 | 默认值 | 使用说明 |
| --- | --- | --- |
| `locale` | `zh_CN` | 默认语言 |
| `time-zone` | `Asia/Shanghai` | 应用时区 |
| `api-prefix` | `CoreApiUrls.API_PREFIX` | 默认 API 前缀；实际地址结合 Controller 与应用配置 |
| `ws-prefix` | `CoreApiUrls.WS_PREFIX` | WebSocket 前缀 |
| `show-api-doc` | `false` | API 文档展示开关，仍受应用安全策略约束 |
| `application-key` | `null` | 应用标识，由装配项目提供 |
| `multi-tenant` | `false` | 是否启用多租户模式 |
| `branch-context-enabled` | `false` | 是否启用经营场所上下文 |
| `tenant-key` | `null` | 单租户配置下的租户标识；不能用任意值代替真实租户语义 |
| `tenant-name` | `IneedFull技术部` | 配置中的默认名称 |
| `is-development` | `false` | 开发模式，具体身份接入依赖安全模块 |
| `i18n-enabled` | `true` | i18n 开关 |
| `cors` | `null` | 未配置；实际 CORS 行为还要查看 Web 配置 |
| `temp-directory` | `null` | 临时目录覆盖项 |

Spring Boot 使用 YAML/properties 与环境覆盖。不要把字段允许 `null` 理解成所有业务流程都能在缺失该配置时运行；租户等规则在实际使用时会校验上下文。

以下只是应用级示例，不能替代数据库、安全或缓存的装配：

```yaml
application:
  application-key: local-training
  multi-tenant: true
  is-development: false
  show-api-doc: false
```

## 外部设施与条件

| 能力 | 配置/依赖入口 | 接入前提 |
| --- | --- | --- |
| JDBC/JPA/MyBatis-Flex | 应用 `spring.datasource.*` | 驱动、DataSource、目标表和正确事务管理器 |
| R2DBC | 应用 `spring.r2dbc.*` | 响应式驱动、ConnectionFactory、响应式事务配置 |
| 阻塞服务缓存 | Spring `CacheManager` + Core 缓存配置 | 缓存管理器存在；Service 显式声明缓存规格 |
| 响应式服务缓存 | Reactive 缓存配置与 store | 匹配的响应式 Redis/store 依赖，不能混入阻塞运行时 |
| 业务集成事件 | `ineed.integration.*` | 开关、资源 key 与监听器，详见事件指南 |
| 会话、身份与授权 | `ineed-security` 所属配置 | Core 本身不能替代安全模块装配 |

`ineed-dev` 四个启动器使用 `MYSQL_HOST`、`MYSQL_PORT`、`MYSQL_USER`、`MYSQL_PASSWORD`、`MYSQL_DATABASE`、`MYSQL_QUARTZ_DATABASE`、`REDIS_HOST`、`REDIS_PORT`、`REDIS_DATABASE` 等环境变量。这些属于开发应用配置，查看 [ineed-dev README](../../../ineed-projects/ineed-dev/README.md) 和所选启动器。集成测试可能使用另一组专用属性，运行前读测试类。

生产值由部署环境提供，不把密码、会话 token 或私钥放入教程。开发配置通过独立 profile 或显式环境变量覆盖，不能直接用于生产。

## 配置不生效时

1. 核对启动器和 classpath 是否选择了正确运行时。
2. 核对生效 profile、属性名和环境覆盖，检查必需 Bean。
3. 区分 Core 属性与业务模块属性，避免把某模块配置误写成 `application.*`。
4. 参考[运行与排错](../getting-started/run-and-verify.md)，用最窄配置测试验证，不靠修改多个开关试错。

源码依据：[ApplicationConfiguration](../../ineed-core-base/src/main/java/com/ineed/base/configuration/ApplicationConfiguration.java)、[阻塞缓存配置](../../ineed-core-modules/ineed-core-service-cache/src/main/java/com/ineed/core/service/cache/ServiceCacheConfiguration.java)、[响应式缓存配置](../../ineed-core-reactive-modules/ineed-core-service-cache-reactive/src/main/java/com/ineed/core/service/cache/reactive/ReactiveServiceCacheConfiguration.java)。

## 文档开关的路径匹配

MVC 与 WebFlux 的文档过滤器按 Spring 路径解析语义单次解码并移除矩阵参数，再匹配文档地址；关闭时 `/v3/%61pi-docs` 与 `/v3/api-docs` 同样返回 404。过滤同时考虑 `scalar.path`、`springdoc.api-docs.path` 及其 YAML 地址。应用安全链仍独立生效。验证见 [MVC 路由测试](../../ineed-core-modules/ineed-core-webmvc/src/test/java/com/ineed/core/webmvc/configuration/ApiDocRoutingTest.java)与 [WebFlux 路由测试](../../ineed-core-reactive-modules/ineed-core-webflux/src/test/java/com/ineed/core/webflux/configuration/ApiDocRoutingTest.java)。