配置参数

配置文件

tio-boot 使用 EnvUtils 统一读取应用参数与私密配置。应用策略可以随 app.properties 发布，密钥保存在不提交的配置文件中，避免散落在业务代码。

文件按以下顺序合并，后加载的同名文件配置覆盖先前值：

1. 用户目录 .env、secrets.txt。
2. 类路径 app.properties、工作目录 app.properties。
3. 类路径 app-环境.properties、工作目录 app-环境.properties。
4. 类路径 .env，工作目录 .env、secrets.txt、my.txt。

加载分为环境选择与配置合并两个阶段。先读取基础文件和本地覆盖文件，结合程序设置、命令行、JVM 属性与环境变量确定 app.env，再追加对应环境文件。因此工作目录 secrets.txt 中的 app.env=test 也能选择 app-test.properties。环境只选择一次，环境文件中的 app.env 不会触发另一个环境文件的加载，合并配置中的 app.env 保持为本次选择的环境。环境名称支持字母、数字、下划线和短横线。

环境文件可以省略；存在的文件若解析失败，加载会抛出异常，保留此前已发布的配置，修正文件后可以重试。EnvUtils.load() 与 EnvUtils.load(args) 在首次成功后不重复加载，也不替换首次加载的启动参数；并发启动调用会串行完成初始化。

用户目录私密配置与类路径应用配置会合并保留；同名值按上述顺序确定。工作目录是启动 Java 进程时所在目录，建议从保存本地 secrets.txt 的服务目录启动。类路径中的私密文件会被打包，应优先使用工作目录文件或部署环境变量。

取值优先级为 EnvUtils.set 设置值、命令行参数、JVM 系统属性、系统环境变量、合并后的文件配置。点号名称也可使用大写下划线环境变量形式，例如 server.port 对应 SERVER_PORT。

package com.example.config;

import nexus.io.tio.utils.environment.EnvUtils;

public class LoginConfig {
  public String appId() {
    return EnvUtils.get("WECHAT_MINI_APP_ID");
  }

  public int sessionIdleSeconds() {
    return EnvUtils.getInt("identity.session.idle.seconds", 7200);
  }
}

框架启动时自动加载配置；独立工具程序可先调用 EnvUtils.load()。不要输出 AppSecret、AccessKey、密码或身份加密密钥。

不要在 TioApplication.run 之前调用 EnvUtils.load()

EnvUtils.load() 只会加载一次。如果在 main 方法里先调用它，TioApplication.run 启动时会跳过加载，命令行参数也不再解析，--app.env=prod、--server.port=8080 这样的参数会失效。

public static void main(String[] args) {
  // 错误：--app.env=prod 不会生效
  EnvUtils.load();
  TioApplication.run(App.class, args);
}

框架会自动加载配置，main 方法里不需要调用。确实要在启动前读取配置时，使用 EnvUtils.load(args)，它会同时解析命令行参数。

可执行 JAR 的配置与依赖核对

应用同时引入多个业务模块时，各模块应在自己的 POM 中声明经过验证的 tio-utils 依赖，并与应用选定的框架依赖保持兼容。Maven 会按依赖路径进行选择，较短路径上的传递依赖可能先于其他模块的依赖被选中。维护这些模块时，应优先更新依赖来源模块的声明，重新构建安装，再构建应用，让其他使用该模块的应用也能获得一致的配置加载行为。应用级依赖管理适合统一约束整个依赖图；暂时覆盖依赖后，仍应同步维护来源模块的依赖声明。

构建前可查看实际依赖选择：

mvn dependency:tree -Dincludes=nexus.io:tio-utils -Dverbose

使用 Spring Boot 打包插件时，应用配置位于 BOOT-INF/classes/app.properties，依赖位于 BOOT-INF/lib/。更新底层源码后，需要先安装对应构建产物，再重新打包应用，使可执行 JAR 包含已验证的依赖。配置加载日志中的文件名用于识别读取来源；需要确认业务参数时，应检查参数是否存在，不输出其值。

下面的独立诊断程序只加载配置，不初始化数据库或业务服务。把它放在待验证应用的运行类路径中执行，可以核对实际加载的类、配置资源和必要参数：

package com.example.config;

import nexus.io.tio.utils.environment.EnvUtils;

public class ConfigurationCheck {
  public static void main(String[] args) {
    EnvUtils.load(args);
    ClassLoader loader = Thread.currentThread().getContextClassLoader();
    if (loader == null) {
      loader = EnvUtils.class.getClassLoader();
    }
    System.out.println("Configuration resource: " + loader.getResource("app.properties"));
    System.out.println("Configuration loader: " + EnvUtils.class.getResource("EnvUtils.class"));
    String jdbcUrl = EnvUtils.get("jdbc.url");
    if (jdbcUrl == null || jdbcUrl.trim().isEmpty()) {
      throw new IllegalStateException("Required configuration jdbc.url is missing");
    }
    System.out.println("Database configuration is present");
  }
}

数据库初始化与表初始化应按顺序执行：先读取配置、启动数据源与 ActiveRecord 插件，再执行表初始化。需要数据库的应用可以在启动数据源前校验必需参数，便于明确定位配置条件。

常用配置

配置加载职责与追加

Prop 负责单文件读取与属性合并；PropUtils 提前创建独立的全局配置对象，后续加载将属性追加到该对象，后追加的同名属性覆盖已有值。单文件缓存与全局配置分离，缓存键包含文件来源和编码，可以区分不同目录的同名文件。

PropUtils.use(filename) 只加载并追加指定文件。需要环境文件时使用 EnvUtils.load(filename)，或者通过 EnvUtils.load(env, filename) 显式指定环境。这两个具名加载方法每次调用都会执行追加，不受默认启动加载的一次性标记限制。旧的 PropUtils.use(filename, env) 重载保留兼容入口，环境处理委托给 EnvUtils。

package com.example.config;

import nexus.io.tio.utils.environment.EnvUtils;
import nexus.io.tio.utils.environment.PropUtils;

public class ConfigurationExample {
  public static void main(String[] args) {
    EnvUtils.load(args);
    // Append a single optional file after startup configuration.
    PropUtils.appendIfExists("feature.properties");
    // Append billing.properties and its optional billing-test.properties.
    EnvUtils.load("test", "billing.properties");
    int timeout = EnvUtils.getInt("billing.timeout.seconds", 30);
    System.out.println("Billing timeout: " + timeout);
  }
}

appendIfExists 跳过不存在的文件，存在但格式不正确的文件会报告错误。PropUtils.useless(filename) 仅移除单文件缓存；PropUtils.clear() 清空全局属性和缓存，保留全局对象本身，不重置 EnvUtils 的启动加载标记。业务启动代码通常无需调用这两个清理方法。

设置静态文件目录

将 app.properties 中配置

server.resources.static-locations = classpath:/pages

将静态文件放到 pages 目录下即可 DefaultHttpRequestHandler 的 processStatic 类会处理静态文件

设置文件上传大小

# 设置最大请求大小（包含所有文件）单位 字节,这里设置为1G
http.multipart.max-request-size=73741824
# 设置最大文件大小,单位字节,这里设置为1G
http.multipart.max-file-size=73741824

默认允许的文件大小是2M,超过2M会出现下面的的错误

Request body is too large. Current size: 9114425 bytes (8.69 MB), max allowed: 2097152 bytes (2.00 MB).

设置为10M,10 * 1024 * 1024 = 10485760

http.multipart.max-request-size=10485760
http.multipart.max-file-size=10485760

配置概览

• server.address=127.0.0.1：指定服务器监听的 IP 地址。此处为本地地址，意味着服务器仅在本机上可访问。
• server.port=8080：定义服务器监听的端口号。在这里，端口被设置为 8080。
• server.listening.enable=true: 是否监听端口
• server.context-path=/myapp：设置应用的上下文路径，这里的应用将通过 /myapp 路径访问。
• server.404=/404：定义 404 错误（页面未找到）时的路由地址。用户将被重定向到 /404 路径。
• server.500=/500：指定 500 错误（服务器内部错误）时的路由地址。对应的路径是 /500。
• server.resources.static-locations=classpath:/pages：设定静态页面的位置，此例中静态资源位于类路径下的 /pages 目录,默认值也是 classpath:/pages。
• server.resources.auto.reload=true: 是否开启静态文件自动加载,开启后在运行是 修改静态文件会立即生效
• server.heartbeat.timeout: 设置心跳检测时间,单位毫秒,同时兼容 server.beartbeat.timeout 写法
• server.session.enable: 开启 session,默认禁用
• server.read.buffer.size: 设置读取数据的缓冲区大小
• server.dev.mode=true：开启或关闭开发模式。当设为 true 时，将启用更详细的日志记录，并激活其他框架的开发模式特性，如热加载功能。
• server.http.request.printUrl : 打印请求地址
• server.enable.session：是否开启使用 HTTP 会话。
• server.http.controller.printMapping：决定是否在启动时打印路由映射信息，有助于调试路由问题。
• server.http.controller.writeMapping：选择是否将路由信息写入文件，便于记录和审查。
• server.http.request.printReport：设置是否打印请求信息。这通常在开发环境下使用，以便于跟踪和调试。
• http.max.live.time.of.static.res=0：设置页面文件的缓存时间。在开发环境中，通常设置为 0 以禁用缓存，而在生产环境中，可以设置为较长的时间（如 3600 秒或 600 秒）以提高性能。
• http.enable.request.limit: 是否开启请求限流
• http.max.requests.per.second : 开启限流后,每秒请求数量,默认 10
• http.checkHost：用于检查和验证 HTTP 请求的主机头。
• http.multipart.max-request-size: 设置请求体的大小
• http.multipart.max-file-size: 设置上传文件的大小
• http.response.showExceptionDetails: 当请求出现异常时,在 HttpResponse 中显示异常信息,默认是是 false
• http.response.header.showServer: 用于控制是否在 HTTP 响应头中添加 Server 信息
• app.env：定义应用的运行环境。根据 app.env 的不同值，可以加载不同的配置文件，以适应不同的开发、测试或生产环境。
• tcp.core.diagnostic=true:显示 tio-core 运行过程中的一些调试信息
• app.tenant=1

tio-boot 配置参考源码 nexus.io.tio.boot.constatns.ConfigKeys

调优配置

server.protocol

server.protocol=http

用于指定服务器对外通信时所使用的协议类型，不同取值将直接影响服务器可接受的连接方式以及底层网络实现。

可选值说明：

• auto 自动模式。服务器会根据客户端的连接方式自动适配，支持 HTTP、WebSocket 以及 TCP 三种协议，适合需要兼容多种客户端或部署环境的场景。

• http 仅启用 HTTP 协议。服务器只接受标准 HTTP 请求，不支持 WebSocket 或 TCP 直连，适用于纯 HTTP 接口服务。

• websocket 仅启用 WebSocket 协议。服务器只接受 WebSocket 连接，适合需要长连接、实时通信的场景。

• tcp 仅启用 TCP 协议。服务器通过原生 TCP 方式进行通信，通常用于自定义协议或高性能、低开销的内部服务通信。

使用建议：

• 如果不确定客户端类型，或需要同时支持多种接入方式，推荐使用 auto。
• 如果服务对外只暴露 REST 接口，选择 http 更加清晰、安全。
• 实时推送或双向通信场景，建议使用 websocket。
• 对性能或协议控制要求较高的内部系统，可选择 tcp。

server.listening.enable

server.listening.enable 默认值为 true。

当配置为 false 时，tio-boot 不会执行 HTTP Server 启动逻辑，也不会监听端口。

适用场景包括：

• 只需要启动后台任务
• 只需要初始化配置或插件
• 与其他 Web 容器集成时，不希望 Tio Boot 自带 HTTP Server 占用端口
• 在测试环境中不需要启动 HTTP 服务

---