HttpRequest

1. `HttpRequest(Node remote)`

说明: 构造一个 HttpRequest 对象，并设置远程节点。

用法:

Node remoteNode = new Node("127.0.0.1", 8080);
HttpRequest httpRequest = new HttpRequest(remoteNode);

2. `HttpRequest()`

说明: 创建一个无参的 HttpRequest 对象。

用法:

HttpRequest httpRequest = new HttpRequest();

3. `close()`

说明: 关闭此 HttpRequest 的连接。
用法:
```
httpRequest.close();
```

4. `close(String remark)`

说明: 带备注的关闭此 HttpRequest 的连接。

用法:

httpRequest.close("Connection closed due to timeout.");

5. `addParam(String key, Object value)`

说明: 向 HttpRequest 添加一个参数。

用法:

httpRequest.addParam("username", "user123");

6. `forward(String newPath)`

说明: 将 HttpRequest 转发到新的路径。
用法:
```
httpRequest.forward("/new/path");
```

7. `getBodyFormat()`

说明: 获取 HttpRequest 的请求体格式。

用法:

RequestBodyFormat bodyFormat = httpRequest.getBodyFormat();

8. `getUserAgent()`

说明: 获取用户代理字符串。

用法:

String userAgent = httpRequest.getUserAgent();

9. `getHost()`

说明: 获取请求头中的 host 字段值。
用法:
```
String host = httpRequest.getHost();
```

10. `getClientIp()`

说明: 获取真实的客户端 IP 地址。

用法:

String clientIp = httpRequest.getClientIp();

11. `addHeader(String key, String value)`

说明: 添加一个 HTTP 头字段。

用法:

httpRequest.addHeader("Content-Type", "application/json");

18. `getDomain()`

说明: 获取请求域名。

用法:

String domain = httpRequest.getDomain();

13. `getBodyString()`

说明: 获取请求体的字符串表示形式。

用法:

String bodyString = httpRequest.getBodyString();

18. `getChannelContext()`

说明: 获取当前 HTTP 请求的通道上下文。

用法:

ChannelContext channelContext = httpRequest.getChannelContext();

18. `getContentLength()`

说明: 获取请求体的长度。

用法:

int contentLength = httpRequest.getContentLength();

16. `getCookie(String cooiename)`

说明: 根据名称获取一个 Cookie 对象。

用法:

Cookie cookie = httpRequest.getCookie("session_id");

18. `getCookieMap()`

说明: 获取所有 Cookie 的映射。

用法:

Map<String, Cookie> cookieMap = httpRequest.getCookieMap();

18. `getCookies()`

说明: 获取所有 Cookies 的列表。

用法:

List<Cookie> cookies = httpRequest.getCookies();

19. `getHttpConfig()`

说明: 获取 HTTP 配置。

用法:

HttpConfig httpConfig = httpRequest.getHttpConfig();

20. `getHttpSession()`

说明: 获取 HTTP 会话。

用法:

HttpSession httpSession = httpRequest.getHttpSession();

21. `getHeader(String key)`

说明: 获取指定 HTTP 头的值。

用法:

String value = httpRequest.getHeader("Accept");

22. `getIsAjax()`

说明: 判断请求是否是 Ajax 请求。

用法:

Boolean isAjax = httpRequest.getIsAjax();

23. `getIsSupportGzip()`

说明: 判断请求是否

支持 Gzip 压缩。

用法:

Boolean isSupportGzip = httpRequest.getIsSupportGzip();

24. `getParams()`

说明: 获取所有请求参数的映射。

用法:

Map<String, Object[]> params = httpRequest.getParams();

25. `getParam()`

说明: 获取单个请求参数。

用法:

Object param = httpRequest.getParam("key");

26. `getString(String name)`

说明: 获取指定名称的字符串参数。

用法:

String value = httpRequest.getString("name");

27. `getInt(String name)`

说明: 获取指定名称的整型参数。

用法:

Integer intValue = httpRequest.getInt("age");

28. `getRemote()`

说明: 获取远程节点信息。
用法:
```
Node remote = httpRequest.getRemote();
```

29. `getRequestLine()`

说明: 获取请求行信息

用法:

RequestLine requestLine = httpRequest.getRequestLine();

30. `logstr()`

说明: 返回 HttpRequest 的日志字符串，通常包含请求 ID、头部信息和请求体。

用法:

String logString = httpRequest.logstr();

31. `parseCookie(HttpConfig httpConfig)`

说明: 解析 HttpRequest 中的 Cookie 信息。
用法:
```
httpRequest.parseCookie(httpConfig);
```

32. `setBodyFormat(RequestBodyFormat bodyFormat)`

说明: 设置 HttpRequest 的请求体格式。

用法:

httpRequest.setBodyFormat(RequestBodyFormat.JSON);

33. `setBodyString(String bodyString)`

说明: 设置 HttpRequest 的请求体内容。

用法:

httpRequest.setBodyString("{\"name\":\"John\"}");

34. `setChannelContext(ChannelContext channelContext)`

说明: 设置 HttpRequest 的通道上下文。

用法:

httpRequest.setChannelContext(channelContext);

35. `setCharset(String charset)`

说明: 设置 HttpRequest 的字符集。
用法:
```
httpRequest.setCharset("UTF-8");
```

36. `setContentLength(int contentLength)`

说明: 设置 HttpRequest 的内容长度。
用法:
```
httpRequest.setContentLength(1024);
```

说明: 设置 HttpRequest 的 Cookie 映射。
用法:
```
httpRequest.setCookieMap(cookieMap);
```

说明: 设置 HttpRequest 的 Cookies 列表。
用法:
```
httpRequest.setCookies(cookies);
```

39. `setHeaders(Map<String, String> headers)`

说明: 设置 HttpRequest 的头部信息。

用法:

Map<String, String> headers = new HashMap<>();
headers.put("Content-Type", "application/json");
httpRequest.setHeaders(headers);

40. `setHttpConfig(HttpConfig httpConfig)`

说明: 设置 HttpRequest 的 HTTP 配置。
用法:
```
httpRequest.setHttpConfig(httpConfig);
```

41. `setHttpSession(HttpSession httpSession)`

说明: 设置 HttpRequest 的 HTTP 会话。

用法:

httpRequest.setHttpSession(httpSession);

42. `setIsAjax(Boolean isAjax)`

说明: 设置 HttpRequest 是否为 Ajax 请求。
用法:
```
httpRequest.setIsAjax(true);
```

43. `setIsSupportGzip(Boolean isSupportGzip)`

说明: 设置 HttpRequest 是否支持 Gzip 压缩。
用法:
```
httpRequest.setIsSupportGzip(true);
```

44. `setParams(Map<String, Object[]> params)`

说明: 设置 HttpRequest 的参数映射。

用法:

Map<String, Object[]> params = new HashMap<>();
params.put("key", new Object[]{"value"});
httpRequest.setParams(params);

45. `setRemote(Node remote)`

说明: 设置 HttpRequest 的远程节点信息。

用法:

httpRequest.setRemote(new Node("127.0.0.1", 8080));

46. `setRequestLine(RequestLine requestLine)`

说明: 设置 HttpRequest 的请求行。

用法:

RequestLine requestLine = new RequestLine("GET", "/api/data", "HTTP/1.1");
httpRequest.setRequestLine(requestLine);

47. `toString()`

说明: 返回 HttpRequest 对象的字符串表示。

用法:

String httpRequestString = httpRequest.toString();

48. `isClosed()`

说明: 检查 HttpRequest 是否已关闭。

用法:

boolean isClosed = httpRequest.isClosed();

49. `setClosed(boolean closed)`

说明: 设置 HttpRequest 的关闭状态。
用法:
```
httpRequest.setClosed(true);
```

50. `getConnection()`

说明: 获取 HttpRequest 的连接信息

。

用法:

String connection = httpRequest.getConnection();

51. `setConnection(String connection)`

说明: 设置 HttpRequest 的连接信息。

用法:

httpRequest.setConnection("keep-alive");

52. `getReferer()`

说明: 获取请求头中的 Referer 字段。

用法:

String referer = httpRequest.getReferer();

53. `isNeedForward()`

说明: 检查 HttpRequest 是否需要转发。

用法:

boolean needForward = httpRequest.isNeedForward();

54. `setNeedForward(boolean needForward)`

说明: 设置 HttpRequest 是否需要转发。
用法:
```
httpRequest.setNeedForward(true);
```

55. `isForward()`

说明: 检查 HttpRequest 是否正在转发。

用法:

boolean isForwarding = httpRequest.isForward();

56. `setForward(boolean isForward)`

说明: 设置 HttpRequest 的转发状态。
用法:
```
httpRequest.setForward(true);
```

57. `getRequestMap()`

返回一份可修改的参数 Map，只包含框架已经解码的查询与表单参数，不解析 JSON 正文。重复参数取第一个值，修改返回值不会改变原有参数表。getParam()、getObject()、getLong() 等方法保持原有取值规则。

import com.jfinal.kit.Kv;
import nexus.io.model.body.RespBodyVo;
import nexus.io.tio.boot.http.TioRequestContext;
import nexus.io.tio.http.common.HttpRequest;
import nexus.io.tio.http.common.HttpResponse;
import nexus.io.tio.utils.validator.ParameterValidator;

public class FormTitleHandler {
  public HttpResponse handle(HttpRequest request) {
    Kv parameters = Kv.create().set(request.getRequestMap());
    String title = ParameterValidator.text(parameters.get("title"), "title", 200);
    return TioRequestContext.getResponse().respond(RespBodyVo.ok(title));
  }
}

application/x-www-form-urlencoded 和 multipart/form-data 的字段由框架按 Content-Type 解码，应用无需再次解析表单正文。
JSON 请求没有查询或表单参数时返回空 Map，即使正文包含字段。读取参数集合不会触发 JSON 格式校验。
文本正文使用 getBodyString()，二进制正文使用 getBodyBytes()。请求大小统一由框架解码层配置控制。

JSON 正文：`getBodyObject(Class<T>)`

确定的 JSON 字段使用请求实体，可以直接读取：

import com.example.model.VideoGenerationRequest;
import nexus.io.tio.http.common.HttpRequest;

public class VideoParameters {
  public VideoGenerationRequest read(HttpRequest request) {
    return request.getBodyObject(VideoGenerationRequest.class);
  }
}

实体单独放在 model 包下：

package com.example.model;

public record VideoGenerationRequest(String prompt, Integer duration) {
}

该方法等价于显式读取并解析正文：

import com.example.model.VideoGenerationRequest;
import nexus.io.tio.http.common.HttpRequest;
import nexus.io.tio.utils.json.JsonUtils;

public class VideoJsonParameters {
  public VideoGenerationRequest read(HttpRequest request) {
    String bodyString = request.getBodyString();
    return JsonUtils.parse(bodyString, VideoGenerationRequest.class);
  }
}

getBodyObject() 使用配置的 JSON provider，只解析当前正文，不合并查询或表单字段，也不缓存结果。它沿用 JsonUtils.parse 的空值、类型转换和异常规则，不做必填或业务校验。需要统一参数异常时，使用 ParameterValidationUtils.body(request, type)，再在校验工具中调用 ParameterValidator，由全局异常处理器捕获 ParameterValidationException。

动态 JSON 字段可以先解析 Map，再包装为 Kv：

import java.util.Map;
import com.jfinal.kit.Kv;
import nexus.io.tio.http.common.HttpRequest;
import nexus.io.tio.utils.json.JsonUtils;

public class DynamicJsonParameters {
  public Kv read(HttpRequest request) {
    String bodyString = request.getBodyString();
    Map<String, Object> map = JsonUtils.parseToMap(bodyString, String.class, Object.class);
    return Kv.create().set(map);
  }
}

例如请求地址为 /video?duration=99、JSON 正文为 {"prompt":"演示","duration":10}，getRequestMap() 读取到查询值 "99"，getBodyObject(VideoGenerationRequest.class) 读取到正文值 10。正文未提供 duration 时，请求实体中的该字段为 null，不会从查询参数补入。

58. `getBearerToken()`

从 Authorization 请求头提取 token，返回类型为 String。对应 nexus.io.tio.http.common.HttpRequest，随 tio-http-common 提供。

String authorization = request.getAuthorization(); // 原始请求头
String token = request.getBearerToken();           // 去掉精确的 "Bearer " 前缀

当前实现等价于：

public String getBearerToken() {
  String token = getAuthorization();
  return token != null && token.startsWith("Bearer ") ? token.substring(7) : token;
}

Authorization 请求头	返回值
未提供	`null`
`Bearer example-token`	`example-token`
`example-token`	`example-token`
`Bearer` （末尾一个空格）	空字符串
`bearer example-token`	原值 `bearer example-token`
`Basic abc`	原值 `Basic abc`
`Bearer example-token` （前缀后多一个空格）	`example-token`，保留额外空白

前缀匹配区分大小写，不会调用 trim()，不会读取 URL 参数或名为 token 的独立请求头，也不会修改原始 Authorization。这里描述的是当前方法实现，不是对 HTTP 认证方案大小写规则的重新定义。

该方法只提取字符串，不验证 JWT 签名、有效期、会话撤销状态或业务权限。受保护的入口仍应在身份验证拦截器中验证 token；公开接口可允许返回 null。Handler 和 Service 无需重复拆分 Authorization，直接使用 request.getBearerToken() 即可。

如果源码已有该方法，但业务工程编译提示找不到符号，需要重新构建并安装包含该方法的 tio-http-common，再重新编译业务工程；仅修改源码不会更新本地 Maven 仓库中的 JAR。

在 Handler 中校验参数

nexus.io.tio.utils.validator.ParameterValidator 是无状态校验工具，不持有 HTTP 请求：

方法	用途
`text(value, name, max, required)`	检查字符串类型、去除首尾空白、必填与最大长度
`id(value, name)`	校验正整数，支持十进制字符串与整数值
`longValue(value, name, min, max, fallback)`	检查整数格式和范围；拒绝小数与溢出
`choice(value, name, fallback, options...)`	检查枚举值
`object(value, name)`	检查 Map 类型及字符串键；null 返回空 Map
`array(value, name, max)`	检查 List 类型和元素数量；null 返回空 List
`require(condition, message)`	检查附加的参数约束

校验失败抛出 java-model 的 nexus.io.model.exception.ParameterValidationException，建议在全局异常处理器中捕获并返回 HTTP 400。它不代表身份验证或业务权限检查：租户、对象归属、余额与状态变更仍应由拦截器和 Service 分别处理。

统一请求体大小配置

http.max-request-body-size 为非 multipart 正文的字节上限，默认 0，表示沿用总请求上限。http.multipart.max-request-size 仍限制所有请求正文总大小；两者同时配置时，非 multipart 请求取较小值。multipart 上传沿用总请求与文件配置，不受普通正文上限影响。解码器在读取 Content-Length 时校验，在分配正文接收缓冲区前拒绝超限请求，无需在每个 Handler 中检查字符串长度。参数示例见请求校验与响应转换。

HTTP 参数绑定为实体

tio-http-common 的 ParameterValidationUtils.body(request, type) 对非空 JSON 对象正文调用 getBodyObject(type)，对表单或空正文的已有参数使用 getRequestMap() 绑定实体。JSON 正文独立于查询参数，非法 JSON、非对象正文和类型转换失败统一抛出 ParameterValidationException。字段必填与业务规则继续交给 ParameterValidator。用法及完整 import 示例见请求校验与响应转换。

判断请求媒体类型

getContentType() 返回原始 Content-Type 头。需要判断媒体类型时，可以直接调用：

isContentType("application/json")：精确比较媒体类型，忽略大小写、首尾空白及请求头中的 charset、boundary 等参数。
isFormUrlEncoded()：判断是否明确声明为 application/x-www-form-urlencoded。
isJson()：判断是否明确声明为 application/json，支持 Application/JSON; charset=UTF-8 等写法。

缺少请求头时返回 false。isContentType() 的参数应为不带参数的媒体类型，传入 null 或空白返回 false；不支持通配符，也不会把 application/problem+json 当作 application/json。这些方法不修改请求头、不解析正文，也不改变框架原有的正文格式识别规则。缺少 Content-Type 时框架的默认表单解析行为，不等于请求明确声明了表单媒体类型。

import nexus.io.tio.http.common.HttpRequest;
import nexus.io.tio.utils.validator.ParameterValidator;

public class FormParameterValidator {
  public static void requireForm(HttpRequest request) {
    ParameterValidator.require(request.isFormUrlEncoded(),
        "Content-Type must be application/x-www-form-urlencoded");
  }
}

例如 Application/X-Www-Form-Urlencoded; charset=UTF-8 可以通过上述检查，multipart/form-data 则不会。业务接口可以复用这些方法表达自身接受的格式，无需反复拆分 Content-Type 字符串。

JSON 接口也可以使用相同方式限定请求格式，再通过 getBodyObject() 绑定请求实体。isJson() 只检查媒体类型，不检查正文是否为合法 JSON；application/problem+json 等类型需要使用 isContentType() 明确匹配。

import nexus.io.tio.http.common.HttpRequest;
import nexus.io.tio.utils.validator.ParameterValidator;

public class JsonParameterValidator {
  public static void requireJson(HttpRequest request) {
    ParameterValidator.require(request.isJson(),
        "Content-Type must be application/json");
  }
}

单值字符串参数：`getRequestStringMap()`

需要将查询和表单字段交给接收 Map<String, String> 的接口时，可以直接获取已解码的单值字符串参数：

import java.util.Map;
import nexus.io.tio.http.common.HttpRequest;

public class StringParameters {
  public Map<String, String> read(HttpRequest request) {
    return request.getRequestStringMap();
  }
}

返回独立、可修改的 Map，修改结果不改变请求参数。
每个名称必须恰有一个值；重复字段抛出 ParameterValidationException，包括名称 URL 解码后相同的字段。
字符串保持原值，不 trim、不再次 URL 解码；null 值转换为空字符串。
文件、数字及其他非字符串对象抛出 ParameterValidationException，不隐式调用 toString()。
包含查询与已解码表单参数，不解析 JSON 正文；没有参数时返回空 Map。

getRequestMap() 适合普通参数读取，重复字段取首值；getRequestStringMap() 适合要求字段唯一的签名校验等场景。方法本身不限制 Content-Type，调用方按接口要求使用 isFormUrlEncoded() 等方法判断。普通业务接口由全局异常处理器捕获 ParameterValidationException 并返回 RespBodyVo，第三方通知则按对应协议返回回执。