很多模型接入项目把主要精力放在“能否得到回复”，Controller 最终只剩一个接收 Map 的接口。这样虽然开发快，却会把若干问题推迟到生产环境：
客户端拼错字段时被静默忽略。导致业务异常难以定位，
空消息进入模型调用，浪费配额并可能触发异常。
数百条历史消息撑大请求体，导致带宽和响应时间飙升。
非法角色绕过业务约束，造成安全风险。
上游错误又被统一包装成含义模糊的 HTTP 响应，调用方难以做出精准处理。
模型接口为何必须严格边界
模型接口主要需要严格的入参边界。按理说，它通常连接按量计费或有配额限制的外部服务。输入还可能包含隐私数据，参数校验不能解决提示词注入，也不能代替内容合规审查。但它至少能在发起上游请求之前完成结构、长度、枚举值和业务关系检查，减少无效调用，并为调用方提供稳定的错误契约。
技术选型
这篇文章使用 Spring Boot 3.x 风格的 jakarta.validation API 展示实现。若项目仍使用 Spring Boot 2.x，需要将相关导入改为 javax.validation并依据项目实际依赖调整配置；不要仅复制包名后假定行为完全相同。
请求进入 Controller 前发生了什么
对于带有 @RequestBody 的 JSON 请求，典型处理链可以简化为四步：
Spring 根据 Content-Type 选择 HttpMessageConverter。
Jackson 将请求体反序列化为 Java DTO；类型错误、非法枚举或 JSON 语法错误会在这一阶段失败。
@Valid 或 @Validated 触发 Bean Validation，检查长度、空值及嵌套对象约束。
Controller 执领域务级校验，接下来调用模型适配器。
这几个阶段产生的异常并不相同。JSON 无法解析通常对应 HttpMessageNotReadableExceptionBean Validation 失败对应 MethodArgumentNotValidException. 如果不做统一处理，调用方很难获得可预测的错误格式。
痛点： 未知字段默认被忽略，使得前端拼写错误或版本漂移难还有时发现。
如何防止未知字段沉默通过
默认配置可能允许客户端提交 DTO 中不存在的属性。说起来，例如调用方误写 maxToken。服务端可能忽略它并采用默认值。说起来，对于公开 API。更稳妥的做法是拒绝未知字段，让契约漂移尽早暴露。
从第一步先来看，准备依赖与严格反序列化配置
MVC 服务需要 Web、Validation 依赖；示例使用 WebClient 调用上游，所以再加入 WebFlux 依赖。但服务端仍可继续采用 Spring MVC：
org.springframework.boot
spring-boot-starter-web
org.springframework.boot
spring-boot-starter-validation
org.springframework.boot
spring-boot-starter-webflux
Pain point: 如果忘记加入 validation starter，Bean Validation 注解将失效，从而让非法请求直接到达模型层。
Simplify configuration:
spring:
jackson:
deserialization:
fail-on-unknown-properties: true
model的观点是。base-url: ${MODEL_BASE_URL}
api-key: ${MODEL_API_KEY}
至于name，${MODEL_NAME}
Pain point: 不要允许客户端直接提交 *base-url*. 否则服务端可能被利用去访问内网地址，形成安全隐患。话说回来，上游地址应由部署配置确定，客户端只提交业务参数。
至于接下来，用 DTO 表达输入契约
不要让外部请求直接绑定到数据库实体。也不要用无约束的 Map. 可以把接口输入定义为不可变
package com.example.chat.api;不过，import jakarta.validation.Valid;import jakarta.validation.constraints.*;import java.util.List;public record ChatRequest(
@NotEmpty
@Size
List<@Valid MessageInput> messages,@Min
@Max
Integer maxTokens) {
public record MessageInput(
@NotNull Role role。@NotBlank
@Size
String content) {}
public enum Role {
USER,ASSISTANT
}
}
Pain point： 角色使用枚举，不接受任意字符串，从而防止非法角色注入程序指令。
Pain point： @Size 限制历史消息条数，避免一次性发送数百条历史记录导致费用暴涨或超时。
Pain point： SYSTEM 角色未暴露给外部，仅由服务端内部生成程序提示词控制。
TIPS: 字符数不等于 token 数，仅用作入口保护；若需精准控制 token，请在后续层使用对应模型的 tokenizer 或保守预算策略。
：在 Controller 中补充业务关系校验
package com.example.chat.api;import jakarta.validation.Valid;import org.springframework.http.MediaType;import org.springframework.web.bind.annotation.*;@RestController
@RequestMapping
public class ChatController {
private final ModelClient modelClient;public ChatController {
this.modelClient = modelClient;}
@PostMapping(
consumes = MediaType.APPLICATION_JSON_VALUE,produces = MediaType.APPLICATION_JSON_VALUE)
public ChatResponse chat {
var last = request.messages.get.size - 1);if，= ChatRequest.Role.USER) {
throw new RequestRuleException;}
return modelClient.complete;}
}
public class RequestRuleException extends RuntimeException {
public RequestRuleException {
super;}
}
Pain point： 即使前端页面没有展示这些字段，攻击者仍可自行构造 HTTP 请求。所有关键配置必须硬编码或从安全存储读取，而不是通过请求体传递。
再看第四步，隔离上游模型协议
package com.example.chat.api;import com.fasterxml.jackson.databind.JsonNode;老实说，import java.util.List;import java.util.Map;import org.springframework.beans.factory.annotation.Value;import org.springframework.stereotype.Component;import org.springframework.web.reactive.function.client.WebClient;@Component
public class ModelClient {
private final WebClient client;
private final String modelName;public ModelClient(WebClient.Builder builder,@Value String baseUrl,@Value String apiKey。@Value String modelName) {
this.client = builder
.baseUrl
.defaultHeaders)
.build;this.modelName = modelName;}
public ChatResponse complete {
List messages = input.messages.stream
.map(m -> Map.of(
"role"。m.role.name.toLowerCase,"content",m.content))
.toList;Map body = Map.of(
"model",modelName。"messages",messages,"max_tokens",input.maxTokens);JsonNode json = client.post
.uri
.bodyValue
.retrieve
.bodyToMono
.block;JsonNode content = json == null?null : json.at;if ) {
throw new UpstreamProtocolException;}
return new ChatResponse);}
}
record ChatResponse {}
Pain point： 代码未展示超时、重试和流式响应。如果生产环境中缺少这些防护，一旦网络抖动或供应商瞬时不可用。就会导致整个链路卡死或重复计费。老实说，请务必在实际实现中加入连接/响应超时、幂等控制还有基于业务需求的重试策略。
从第五步来看，建立统一错误响应
package com.example.chat.api;import java.util.List;import org.springframework.http.HttpStatus;import org.springframework.http.ProblemDetail;import org.springframework.http.converter.HttpMessageNotReadableException;说起来，import org.springframework.web.bind.MethodArgumentNotValidException;import org.springframework.web.bind.annotation.*;@RestControllerAdvice
public class ApiExceptionHandler {
record FieldIssue {}
@ExceptionHandler
ProblemDetail validation {
ProblemDetail detail = ProblemDetail.forStatus;detail.setTitle;List issues = ex.getBindingResult.getFieldErrors.stream
.map,e.getDefaultMessage))
.toList;detail.setProperty;return detail;}
@ExceptionHandler
ProblemDetail unreadable {
ProblemDetail detail = ProblemDetail.forStatus;detail.setTitle;detail.setDetail;return detail;}
@ExceptionHandler
ProblemDetail rule {
ProblemDetail detail = ProblemDetail.forStatus;detail.setTitle;detail.setDetail);return detail;}
}
Pain point： 统一返回结构避免了不同异常产生不同 HTTP 状态码/文本，使前端能够基于固定 schema 做自动化错误展示和重试判断。日志脱敏避免泄露使用者隐私或内部密钥信息。
再看第六步，执行验证与本地测试
export MODEL_BASE_URL='https://provider.example'
export MODEL_API_KEY='replace-with-secret-from-secret-manager'
export MODEL_NAME='model-id-from-provider-docs'
./mvnw spring-boot:run
curl -i http://localhost:8080/api/chat \
-H 'Content-Type: application/json' \
-d '{"messages":。"maxTokens":1024}'
- 验证四类失败：
• "未知字段" : 如提交 {"maxToken":1024}
• "非法枚举" : 如 {"role":"ADMIN"}
• "空白内容" : 如 {"content":""}
• "超出历史条数" : 超过设定上限
网关层大小限制
location /api/chat {
client_max_body_size 256k;proxy_pass http://spring_app;}
Pain point： 仅靠应用层校验无法阻止恶意的大体积上传；话说回来，网关层限制可以在流量到达 Spring 前就丢弃明显异常的数据包。提高整体抗压能力，
常见问题
使用 DTO 后是否就不会发生提示词注入？
No. DTO 校验只能保证结构和基础业务约束，无法判断自然语言是否试图覆盖程序指令。程序比如提示词隔离，还有工具白名单。再有输出审查还有最小权限仍是必需措施。
为什么不直接返回校验异常的原始消息？
The raw exception may expose Java type names,internal field names or parsing details that differ across library versions. A stable contract provides predictable error codes。field paths and human‑readable explanations while keeping stack traces only in controlled logs.
maxTokens 允许客户端控制安全吗？
You can allow it,but you must enforce a server‑side hard ceiling. More advanced setups may apply per‑tenant or per‑model budgets. The final value sent upstream should be intersection of user request。server policy and provider limits.
是否应该自动裁剪过长历史消息？
The decision depends on product contracts. Silent trimming may lose critical context while strict rejection is more predictable but forces clients to handle pagination mselves. If you trim,document trimming rule clearly and surface metadata indicating which messages were dropped.
为什么未知字段要报错？老实说，p> In public APIs rejecting unknown fields helps surface spelling mistakes and version drift early. For internal systems that need gradual compatibility you may choose a tolerant mode。but whichever strategy you adopt must be locked down by contract tests to avoid accidental behavior changes when upgrading Jackson or modifying DTOs.
p>可靠的模型接口不是把 JSON 转发给上游，而是建立清晰的输入边界： 用 DTO 表达结构，用 Bean Validation 检查基础约束，用业务代码处理跨字段规则，用统一错误格式稳定客户端预期，再通过独立适配器隔离不同模型协议。p> 参数绑定只是第一道门。请求体大小、日志脱敏、固定上游地址、服务端 token 预算、超时、错误分层和契约测试共同构成可维护的接入基础。按理说，先让非法请求在本地、可解释地失败，再讨论重试、流式输出和多供应商路由。程序成本与安全边界才不会被一个宽松的 Controller 悄悄绕开。/ p>
