配置参数

配置文件

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、密码或身份加密密钥。

常用配置

配置加载职责与追加

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.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 服务