本文详解 Micronaut 中实现内容协商（Content Negotiation）的两种专业方案：通过多 @Get(produces=...) 方法配合 */* 回退端点避免 400 冲突，以及优化后的单方法手动协商实践，兼顾清晰性与可控性。
本文详解 micronaut 中实现内容协商（content negotiation）的两种专业方案：通过多 `@get(produces=...)` 方法配合 `*/*` 回退端点避免 400 冲突，以及优化后的单方法手动协商实践，兼顾清晰性与可控性。
在构建 RESTful 微服务时，支持根据客户端 Accept 请求头自动适配响应格式（如 text/html、text/plain 或 application/json）是提升 API 兼容性与用户体验的关键能力。Micronaut 原生支持基于 produces 属性的内容协商，但若未显式指定 Accept 头，多个同路径、不同 produces 的端点将触发路由歧义，导致 400 Bad Request 错误——正如你在 / 路径上遇到的 "More than 1 route matched" 问题。
✅ 推荐方案：声明式多端点 + */* 默认回退
Micronaut 允许使用通配符 */* 作为 produces 值，定义一个优先级最低的兜底端点，仅在其他更具体的 produces 不匹配（例如 Accept 头缺失或为 */*）时被选中。这完美解决你的 Question 1：
@Controller("/")
public class IndexController {
@Get(produces = "text/html")
public String indexHtml() {
return """
<!DOCTYPE html>
<html><head><meta charset="utf-8"></head>
<body><h1>Demo service</h1></body></html>""";
}
@Get(produces = "text/plain")
public String indexText() {
return "Demo service\r\n";
}
// ✅ 关键：当 Accept 头缺失或为 */* 时，此方法作为默认回退
@Get(produces = "*/*")
public String indexDefault() {
return "Demo service (plain fallback)";
}
}? 原理说明：Micronaut 的路由匹配器按 produces 的 specificity 降序排序（text/html > text/plain > */*）。当请求不含 Accept 头时，前两个端点因无法验证媒体类型而被跳过，*/* 端点成为唯一匹配项，成功响应 200 OK。
✅ 验证效果：
# 显式请求 HTML → 返回 HTML curl -H "Accept: text/html" http://localhost:8080/ # 显式请求纯文本 → 返回 plain curl -H "Accept: text/plain" http://localhost:8080/ # 无 Accept 头 → 触发 */* 回退，返回 fallback 字符串 curl http://localhost:8080/ # 输出：Demo service (plain fallback)
⚠️ 替代方案：单方法手动协商（适用于复杂逻辑）
当需要精细控制协商逻辑（如支持自定义 MIME 类型、版本协商、或 fallback 到 JSON）、或需复用同一业务逻辑时，可采用单端点 + 手动解析 Accept 头的方式。但你的原始实现存在可优化点：
- ❌ 避免手动遍历 accept() 迭代器（易忽略权重 q 值、多值场景）；
- ✅ 应使用 Micronaut 提供的 HttpRequest.accepts() 工具方法，它已按 q 值排序并过滤无效类型；
- ✅ 结合 MediaType 静态常量增强可读性与类型安全。
优化后的写法如下：
import io.micronaut.http.HttpRequest;
import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
@Controller("/")
public class FlexibleIndexController {
@Get(produces = {MediaType.TEXT_PLAIN, MediaType.TEXT_HTML, MediaType.APPLICATION_JSON})
public Object index(HttpRequest<?> request) {
// ✅ 自动按 q 值排序，返回最匹配的 MediaType（null 表示无有效 Accept）
MediaType bestMatch = request.accepts(
MediaType.TEXT_HTML_TYPE,
MediaType.TEXT_PLAIN_TYPE,
MediaType.APPLICATION_JSON_TYPE
);
if (MediaType.TEXT_HTML_TYPE.equals(bestMatch)) {
return """
<!DOCTYPE html>
<html><body><h1>Demo service (HTML)</h1></body></html>""";
} else if (MediaType.TEXT_PLAIN_TYPE.equals(bestMatch)) {
return "Demo service (plain)\r\n";
} else {
// fallback: 当 Accept 为空、为 */* 或不匹配时，默认返回 JSON
return Map.of("title", "Demo service", "format", "json");
}
}
}? 注意：request.accepts(...) 是 Micronaut 推荐方式，它正确处理了 RFC 7231 定义的 q 参数（如 Accept: text/html;q=0.9,text/plain;q=0.5），无需手动解析。
? 最佳实践总结
| 场景 | 推荐方式 | 关键要点 |
|---|---|---|
| 简单格式切换（HTML/TEXT/JSON） | 多 @Get(produces=...) + */* 回退 | 清晰、无胶水代码、利用框架原生协商能力；*/* 必须显式声明为独立端点 |
| 需高级协商逻辑（如版本、自定义类型、动态内容生成） | 单端点 + request.accepts() | 使用 accepts(MediaType...) 而非原始 accept()，确保符合 HTTP 标准 |
| 避免陷阱 | — | 不要省略 */* 端点（否则无 Accept 时 400）；produces 数组内顺序不影响匹配优先级，仅由声明的 specificity 决定 |
通过合理组合声明式 produces 与语义化回退策略，你既能保持控制器的简洁性，又能确保服务在各种客户端环境下健壮响应——这才是 Micronaut “编译时驱动、零反射”理念下的内容协商最佳实践。
