Huma框架中处理纯文本请求体的最佳实践

在基于Huma框架开发RESTful API时，开发者有时会遇到需要接收纯文本请求体的情况。与常见的JSON格式不同，纯文本请求体不需要结构化解析，而是直接获取原始内容进行处理。本文将详细介绍在Huma框架中正确处理text/plain类型请求体的方法。

常见误区

许多开发者会尝试使用以下两种方式定义请求体结构：

1. 直接使用字符串类型：

type RouteInput struct {
    Body string
}

2. 使用io.Reader接口：

type RouteInput struct {
    Body io.Reader
}

这两种方式都会导致框架默认期望application/json内容类型，无法正确处理text/plain请求。这是因为Huma框架对Body字段有默认的JSON解析逻辑。

正确解决方案

Huma框架提供了专门处理原始请求体的方式，需要使用RawBody字段并配合contentType标签：

type RouteInput struct {
    RawBody []byte `contentType:"text/plain"`
}

这种方式的优势在于：

1. 明确指定了内容类型为text/plain
2. 使用[]byte类型避免框架进行JSON解析
3. 保留了原始请求体的完整内容

实现原理

当使用RawBody字段时，Huma框架会：

1. 跳过常规的请求体解析流程
2. 直接读取HTTP请求的原始body内容
3. 将内容存储到RawBody字段中
4. 确保OpenAPI文档正确生成text/plain内容类型

实际应用示例

以下是一个完整的API端点实现示例：

huma.Register(api, huma.Operation{
    OperationID: "text-processor",
    Method:      http.MethodPost,
    Path:        "/process-text",
}, func(ctx context.Context, input *struct {
    RawBody []byte `contentType:"text/plain"`
}) (*struct{}, error) {
    // 直接处理原始文本内容
    textContent := string(input.RawBody)
    fmt.Println("Received text:", textContent)
    return nil, nil
})

注意事项

1. 如果需要处理多种内容类型，可以在contentType标签中指定多个值
2. 对于大文本内容，建议使用流式处理而非一次性读取全部内容
3. 确保客户端发送请求时正确设置Content-Type头为text/plain

通过正确使用RawBody字段，开发者可以轻松地在Huma框架中实现纯文本请求体的处理功能，同时保持API文档的准确性和一致性。这种方法既简单又高效，是处理非JSON请求体的推荐方式。