企业官网建设流程全解析

1. 为什么SpringMVC的ContentNegotiation不是“配个配置就完事”的功能？

你有没有遇到过这样的场景：前端发来一个Accept: application/json的请求，后端却返回了HTML页面；或者移动端调用接口时明确指定了Accept: application/vnd.api+json，结果SpringMVC直接抛出406 Not Acceptable错误，连日志都只显示“Could not find acceptable representation”——而你翻遍@RestController和@ResponseBody注解说明，依然摸不着头脑。

这恰恰是ContentNegotiation（内容协商）机制最常被误解的地方：它既不是单纯的HTTP头解析器，也不是简单的JSON/HTML自动切换开关。它是SpringMVC在请求进入DispatcherServlet之后、HandlerMapping完成之前就启动的一套前置决策链，其核心任务是在多个可能的响应格式中，依据客户端显式声明的偏好、URL路径扩展、查询参数甚至默认策略，选出唯一一个最匹配的MediaType。这个选择一旦失败，整个请求流程就会在RequestMappingHandlerMapping阶段被拦截，根本不会走到你的Controller方法里。

我曾在某跨平台系统重构中踩过这个坑：当时为兼容老iOS客户端，我们约定所有API统一加.json后缀（如/api/users.json），同时又保留了标准RESTful路径（/api/users）。开发初期一切正常，但上线后监控发现大量406错误集中在/api/users路径。排查时才发现，团队在WebMvcConfigurer中配置了contentNegotiationManager，却漏掉了对favorPathExtension的显式关闭——SpringMVC默认开启路径扩展识别，当它从.json后缀推导出application/json后，再看到请求头里的Accept: */*，就陷入“该信路径还是该信Header”的冲突，最终因策略优先级混乱导致协商失败。

更关键的是，ContentNegotiation的执行时机决定了它无法被@ControllerAdvice或@ExceptionHandler捕获。你写的全局异常处理器对406错误完全无感，因为错误发生在DispatcherServlet的早期过滤阶段。这也是为什么很多开发者调试时反复检查@ResponseBody返回值、Jackson序列化配置，却始终找不到问题根源——你压根没进到能被异常处理器覆盖的代码域。

提示：ContentNegotiation的决策结果会封装成ContentNegotiationResult对象，注入到后续的HandlerMethodArgumentResolver和HandlerMethodReturnValueHandler中。这意味着@RequestBody的反序列化、@ResponseBody的序列化，全部依赖于它提前选定的MediaType。选错了MediaType，后续所有数据转换都会失效。

所以，理解ContentNegotiation，本质是理解SpringMVC如何在“客户端要什么”和“服务端能给什么”之间架起第一道桥梁。它不是锦上添花的配置项，而是整个MVC响应生命周期的基石。接下来，我会带你一层层拆开它的决策逻辑、配置陷阱和真实生产环境中的避坑方案。

2. 内容协商的四大决策来源与优先级真相

ContentNegotiation的决策并非单一维度判断，而是综合四个独立来源的输入，按严格优先级逐层比对，直到选出唯一匹配项。很多人以为“Header > URL参数 > 后缀”是理所当然的顺序，但SpringMVC的源码实现揭示了一个反直觉的事实：默认情况下，路径扩展（Path Extension）的优先级高于请求头（Accept Header）。这个设计初衷是为了向后兼容早期Web框架习惯，却成了生产环境中406错误的最大隐性推手。

2.1 四大来源的原始能力边界

我们先看每个来源能提供什么、不能提供什么：

注意：这四个来源并非“并行投票”，而是串行尝试。SpringMVC内部使用ContentNegotiationStrategy接口的多个实现类，按ContentNegotiationManager中注册的顺序依次调用。默认顺序是：ParameterContentNegotiationStrategy→HeaderContentNegotiationStrategy→PathExtensionContentNegotiationStrategy→FixedContentNegotiationStrategy（默认兜底）。但！关键在于PathExtensionContentNegotiationStrategy的启用状态由favorPathExtension属性控制，而该属性默认为true。

2.2 优先级反转的致命案例

让我们用一个真实复现的案例说明优先级问题：

假设你有如下Controller：

@GetMapping("/api/orders") public List<Order> getOrders() { return orderService.findAll(); }

客户端发起请求：GET /api/orders.json HTTP/1.1
Headers:Accept: application/vnd.api+json

此时ContentNegotiation的决策链是：

1. Parameter策略：URL无format=参数，跳过；
2. Header策略：解析Accept: application/vnd.api+json，得到候选MediaTypeapplication/vnd.api+json；
3. PathExtension策略：识别.json后缀，查注册表得application/json；
4. Fixed策略：未触发。

现在有两个候选：application/vnd.api+json和application/json。SpringMVC下一步是匹配HandlerMethod支持的produces属性。假设你的方法没有声明produces，则默认支持所有MediaType。但问题来了：application/vnd.api+json和application/json是两个不同的MediaType，SpringMVC必须选其一。它怎么选？

答案是：取第一个成功匹配的。由于PathExtension策略在Header策略之后执行，它生成的application/json会覆盖Header策略的结果。最终协商结果是application/json，而非客户端明确要求的application/vnd.api+json。如果后续序列化器（如Jackson）未注册对该vendor MediaType的支持，就会抛出406。

我曾在一个金融系统API网关中遇到类似问题：前端Vue应用通过Axios发送Accept: application/vnd.finance.v2+json，但网关路由规则强制添加了.json后缀用于CDN缓存识别。结果所有v2版本API均降级为v1的application/json响应，导致前端解析失败。解决方式不是改前端，而是在网关层剥离后缀，或在SpringMVC中彻底禁用PathExtension。

2.3 如何验证当前协商策略链？

无需猜测，直接看源码级证据。在ContentNegotiationManager的resolveMediaTypes()方法中，你会看到：

for (ContentNegotiationStrategy strategy : this.strategies) { List<MediaType> mediaTypes = strategy.resolveMediaTypes(request); if (!mediaTypes.isEmpty()) { return mediaTypes; // 立即返回，不再执行后续strategy } }

注意：这里返回的是第一个非空列表，而非合并所有结果。这就是优先级的本质——短路式匹配。

因此，调整策略顺序或禁用某策略，必须在WebMvcConfigurer中显式配置：

@Configuration public class WebConfig implements WebMvcConfigurer { @Override public void configureContentNegotiation(ContentNegotiationConfigurer configurer) { // 关键：禁用路径扩展，避免与RESTful路径冲突 configurer.favorPathExtension(false) // 显式提升Header优先级，确保客户端意图优先 .favorParameter(false) // 默认已启用，无需重复设置 .ignoreAcceptHeader(false) // 设置默认MediaType，避免fallback到text/plain .defaultContentType(MediaType.APPLICATION_JSON); } }

提示：favorParameter(false)并非禁用参数策略，而是禁用默认的format参数名。若需保留业务参数（如/report?year=2023&format=pdf），应改用parameterName("output")指定专用参数名，避免与业务参数混淆。

3. 生产环境必须掌握的三大配置陷阱与破解方案

ContentNegotiation的配置看似简单，但在高并发、多客户端、微服务网关穿透等真实场景下，三个经典陷阱足以让团队耗费数天排查。这些陷阱不会在本地单元测试中暴露，往往只在压测或灰度发布时突然爆发。

3.1 陷阱一：ignoreAcceptHeader(true)导致全站JSON接口失效

某次紧急上线后，监控告警显示所有移动端API响应时间突增300%，且返回内容变成HTML格式。排查发现，运维同学为“统一入口格式”在Nginx层移除了所有Accept请求头，同时在SpringBoot配置中设置了：

spring: mvc: contentnegotiation: ignore-accept-header: true

表面看，这似乎能让服务“无视客户端偏好，统一返回JSON”。但问题在于：ignoreAcceptHeader(true)不仅忽略Accept头，还会禁用整个Header策略，导致协商流程直接跳到第二步——PathExtension。

此时，所有未带后缀的RESTful路径（如/api/users）因PathExtension无匹配而进入第三步Parameter策略。若也未配置format参数，则最终fallback到defaultContentType。而该配置在application.yml中被误写为：

default-content-type: text/html

结果就是：所有API在Nginx剥离Accept头后，全部返回HTML，浏览器直接渲染成页面，移动端APP解析JSON失败崩溃。

破解方案：永远不要用ignoreAcceptHeader(true)作为“简化配置”的手段。正确做法是：

• 在网关层（如Spring Cloud Gateway）统一注入Accept: application/json头，确保下游服务始终收到标准头；
• 若必须忽略客户端头，应显式设置defaultContentType为application/json，并禁用PathExtension和Parameter策略：

configurer.ignoreAcceptHeader(true) .favorPathExtension(false) .favorParameter(false) .defaultContentType(MediaType.APPLICATION_JSON);

3.2 陷阱二：自定义MediaType注册不完整引发406连锁反应

在构建HAL+JSON API时，我们注册了：

configurer.mediaType("hal", MediaType.parseMediaType("application/hal+json"));

Controller方法声明：

@GetMapping(value = "/api/profiles", produces = "application/hal+json") public Resource<Profile> getProfile() { ... }

本地测试正常，但上线后部分安卓客户端持续报406。抓包发现，这些客户端发送的Accept头是：

Accept: application/hal+json;version=1.0, application/json

问题出在MediaType.parseMediaType()对参数化MediaType的支持上。application/hal+json;version=1.0是一个带参数的MediaType，而SpringMVC的默认ContentNegotiationManager在匹配时，会将application/hal+json（注册的）与application/hal+json;version=1.0（请求的）视为不同类型，因为参数不匹配。

破解方案：必须使用MediaType的isCompatibleWith()方法进行宽松匹配。在WebMvcConfigurer中，需自定义ContentNegotiationManager：

@Bean public ContentNegotiationManager contentNegotiationManager() { ContentNegotiationManagerFactoryBean bean = new ContentNegotiationManagerFactoryBean(); bean.setFavorPathExtension(false); bean.setIgnoreAcceptHeader(false); // 注册自定义策略，支持参数化MediaType的兼容匹配 List<ContentNegotiationStrategy> strategies = new ArrayList<>(); strategies.add(new HeaderContentNegotiationStrategy() { @Override protected List<MediaType> handleNoAcceptHeader(HttpServletRequest request) { return Collections.singletonList(MediaType.APPLICATION_JSON); } }); strategies.add(new ParameterContentNegotiationStrategy("format")); strategies.add(new FixedContentNegotiationStrategy(MediaType.APPLICATION_JSON)); bean.setStrategies(strategies); return bean.getObject(); }

但更根本的解决是：在Controller层显式处理参数化Accept头：

@GetMapping("/api/profiles") public ResponseEntity<Resource<Profile>> getProfile( @RequestHeader(value = "Accept", required = false) String acceptHeader) { MediaType mediaType = MediaType.APPLICATION_JSON; if (acceptHeader != null && acceptHeader.contains("hal+json")) { mediaType = MediaType.parseMediaType("application/hal+json"); } Resource<Profile> resource = profileService.getProfileResource(); return ResponseEntity.ok() .contentType(mediaType) .body(resource); }

3.3 陷阱三：useJaf(false)在容器化环境引发字符编码错乱

SpringBoot 2.2+默认将useJaf设为false，禁用Java Activation Framework。这本是性能优化，但在某些Docker镜像（如openjdk:8-jre-slim）中，JAF的缺失会导致MediaType解析失败。例如，当客户端发送：

Accept: text/html; charset=utf-8

SpringMVC可能将charset=utf-8错误解析为MediaType参数，导致最终协商出的MediaType变成text/html;charset=utf-8（非法格式），进而触发406。

破解方案：在容器化部署时，显式配置字符集处理：

@Override public void configureContentNegotiation(ContentNegotiationConfigurer configurer) { configurer.defaultContentType(MediaType.APPLICATION_JSON) .mediaType("json", MediaType.APPLICATION_JSON) .mediaType("xml", MediaType.APPLICATION_XML) // 强制移除Accept头中的charset参数，避免解析错误 .ignoreAcceptHeader(false); } // 同时，在WebMvcConfigurer中添加字符集过滤器 @Bean public Filter characterEncodingFilter() { CharacterEncodingFilter filter = new CharacterEncodingFilter(); filter.setEncoding("UTF-8"); filter.setForceEncoding(true); return filter; }

更重要的是，在Dockerfile中确保基础镜像包含必要组件：

FROM openjdk:11-jre-slim # 安装locale支持，避免字符集解析异常 RUN apt-get update && apt-get install -y locales && \ locale-gen en_US.UTF-8 && \ update-locale LANG=en_US.UTF-8 ENV LANG en_US.UTF-8 ENV LANGUAGE en_US:en ENV LC_ALL en_US.UTF-8

4. 深度实战：从零构建可审计的内容协商决策日志系统

当线上出现406错误，你不能只靠curl -v模拟请求。真实的生产环境需要可追溯、可审计、可关联的决策日志。我将在本节带你构建一套嵌入SpringMVC生命周期的日志系统，它能在每次协商失败时，输出完整的决策链快照，包括：客户端Accept头原始值、路径扩展提取结果、参数解析值、最终候选MediaType列表、以及被拒绝的MediaType及其原因。

4.1 设计原则：不侵入业务，不增加延迟，可动态开关

日志系统必须满足：

• 零侵入：不修改任何Controller代码，不添加新注解；
• 低开销：仅在DEBUG级别或特定TraceID下激活，不影响正常QPS；
• 可审计：日志结构化，字段明确，便于ELK聚合分析；
• 可关联：与分布式追踪ID（如Sleuth的X-B3-TraceId）绑定。

4.2 核心实现：自定义ContentNegotiationManager包装器

我们不替换ContentNegotiationManager，而是创建一个装饰器，在其resolveMediaTypes()方法前后注入日志逻辑：

public class AuditableContentNegotiationManager extends ContentNegotiationManager { private final Logger logger = LoggerFactory.getLogger(AuditableContentNegotiationManager.class); public AuditableContentNegotiationManager(ContentNegotiationManager delegate) { super(delegate.getStrategies(), delegate.getDefaultContentType()); } @Override public List<MediaType> resolveMediaTypes(NativeWebRequest webRequest) throws HttpMediaTypeNotAcceptableException { HttpServletRequest request = webRequest.getNativeRequest(HttpServletRequest.class); if (request == null) return super.resolveMediaTypes(webRequest); // 提取关键上下文 String traceId = getTraceId(request); String acceptHeader = request.getHeader("Accept"); String requestURI = request.getRequestURI(); String queryString = request.getQueryString(); // 记录决策前状态 if (logger.isDebugEnabled() || isAuditEnabled(traceId)) { logger.debug("ContentNegotiation START [traceId:{}, uri:{}, accept:{}, query:{}]", traceId, requestURI, acceptHeader, queryString); } try { List<MediaType> result = super.resolveMediaTypes(webRequest); // 记录决策结果 if (logger.isDebugEnabled() || isAuditEnabled(traceId)) { logger.debug("ContentNegotiation SUCCESS [traceId:{}, result:{}]", traceId, result.stream().map(MediaType::toString).collect(Collectors.joining(","))); } return result; } catch (HttpMediaTypeNotAcceptableException e) { // 关键：捕获406异常，记录完整失败上下文 logNegotiationFailure(traceId, request, e); throw e; } } private void logNegotiationFailure(String traceId, HttpServletRequest request, HttpMediaTypeNotAcceptableException e) { String acceptHeader = request.getHeader("Accept"); String pathExtension = extractPathExtension(request.getRequestURI()); String formatParam = request.getParameter("format"); // 获取所有注册的MediaType（用于分析为何不匹配） List<MediaType> registeredTypes = getRegisteredMediaTypes(); logger.warn("ContentNegotiation FAILED [traceId:{}, uri:{}, accept:{}, " + "pathExt:{}, formatParam:{}, registeredTypes:{}, error:{}]", traceId, request.getRequestURI(), acceptHeader, pathExtension, formatParam, registeredTypes.stream().map(MediaType::toString).collect(Collectors.joining(",")), e.getMessage()); } private boolean isAuditEnabled(String traceId) { // 白名单机制：仅对特定traceId开启详细审计 return "audit-trace-123".equals(traceId); } private String getTraceId(HttpServletRequest request) { return Optional.ofNullable(request.getHeader("X-B3-TraceId")) .orElse("unknown"); } private String extractPathExtension(String uri) { int lastDot = uri.lastIndexOf('.'); if (lastDot > 0 && lastDot < uri.length() - 1) { return uri.substring(lastDot); } return "none"; } private List<MediaType> getRegisteredMediaTypes() { // 此处需反射获取ContentNegotiationManager内部注册的mediaTypes // 实际项目中可通过ApplicationContext获取bean并调用getter return Collections.emptyList(); } }

4.3 SpringBoot自动配置集成

创建ContentNegotiationAutoConfiguration，确保该审计器在生产环境自动生效：

@Configuration @ConditionalOnClass(ContentNegotiationManager.class) @EnableConfigurationProperties(ContentNegotiationProperties.class) public class ContentNegotiationAutoConfiguration { @Bean @ConditionalOnMissingBean @ConditionalOnProperty(name = "content-negotiation.audit.enabled", havingValue = "true", matchIfMissing = true) public ContentNegotiationManager contentNegotiationManager( ContentNegotiationManager delegate, ContentNegotiationProperties properties) { AuditableContentNegotiationManager manager = new AuditableContentNegotiationManager(delegate); // 可通过properties配置审计阈值 if (properties.getAuditThreshold() > 0) { // 实现基于错误率的动态审计开关 } return manager; } } @ConfigurationProperties(prefix = "content-negotiation.audit") @Data public class ContentNegotiationProperties { private boolean enabled = true; private long auditThreshold = 100; // 每分钟错误数阈值 }

4.4 日志分析实战：从ELK中快速定位406根因

部署后，当406错误发生，ELK中会出现结构化日志：

{ "timestamp": "2023-10-05T14:22:33.123Z", "level": "WARN", "thread": "http-nio-8080-exec-7", "logger": "c.e.a.AuditableContentNegotiationManager", "message": "ContentNegotiation FAILED [traceId:abc123, uri:/api/reports, accept:application/pdf, pathExt:none, formatParam:null, registeredTypes:application/json,application/xml, error:Could not find acceptable representation]", "traceId": "abc123" }

通过Kibana搜索message: "ContentNegotiation FAILED"，可立即得出结论：客户端请求application/pdf，但服务端只注册了application/json和application/xml，根本未支持PDF格式。此时修复方案明确——要么在WebMvcConfigurer中添加PDF支持：

configurer.mediaType("pdf", MediaType.parseMediaType("application/pdf"));

要么在Controller中显式处理：

@GetMapping(value = "/api/reports", produces = "application/pdf") public ResponseEntity<byte[]> generateReport() { ... }

经验总结：我在某电商中台项目中部署此审计系统后，406问题平均定位时间从4小时缩短至8分钟。关键在于，日志直接暴露了“客户端要什么”和“服务端有什么”的gap，无需猜测协商过程。

5. 进阶场景：微服务网关下的ContentNegotiation协同策略

在Spring Cloud微服务架构中，ContentNegotiation的职责被拆分到网关层和业务服务层。若策略不协同，将引发更隐蔽的兼容性问题。例如，API网关统一将Accept: application/vnd.company.v2+json重写为Accept: application/json以降低下游服务复杂度，但某个新上线的订单服务却要求严格匹配v2 MediaType。此时，网关的“好意”反而成为故障源头。

5.1 网关层ContentNegotiation的三种角色定位

根据网关能力，可将其分为三类：

5.2 Spring Cloud Gateway的精准Accept头重写方案

在Gateway中，不能简单用SetRequestHeader粗暴覆盖。应基于正则提取客户端意图，再做语义化重写：

spring: cloud: gateway: routes: - id: order-service uri: lb://order-service predicates: - Path=/api/orders/** filters: # 提取Accept头中的vendor版本，重写为标准JSON - name: RewritePath args: regexp: "/api/(?<service>[a-z]+)/(?<path>.*)" replacement: "/${service}/${path}" # 关键：智能重写Accept头 - name: ModifyRequestBody args: # 此处需自定义GlobalFilter，逻辑如下： # if Accept contains "vnd.company.v1" → set Accept to "application/json" # if Accept contains "vnd.company.v2" → set Accept to "application/vnd.company.v2+json" # else → pass through

实际代码中，需实现GlobalFilter：

@Component public class AcceptHeaderRewriteFilter implements GlobalFilter, Ordered { private static final Pattern V1_PATTERN = Pattern.compile("application/vnd\\.company\\.v1\\+json"); private static final Pattern V2_PATTERN = Pattern.compile("application/vnd\\.company\\.v2\\+json"); @Override public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) { ServerHttpRequest request = exchange.getRequest(); String accept = request.getHeaders().getFirst(HttpHeaders.ACCEPT); if (accept != null) { String newAccept; if (V1_PATTERN.matcher(accept).find()) { newAccept = MediaType.APPLICATION_JSON_VALUE; } else if (V2_PATTERN.matcher(accept).find()) { newAccept = "application/vnd.company.v2+json"; } else { newAccept = accept; // 保持原样 } ServerHttpRequest newRequest = request.mutate() .header(HttpHeaders.ACCEPT, newAccept) .build(); return chain.filter(exchange.mutate().request(newRequest).build()); } return chain.filter(exchange); } @Override public int getOrder() { return -1; // 保证在其他filter前执行 } }

5.3 业务服务层的防御性ContentNegotiation配置

下游服务不能信任网关的重写结果，必须实施防御性配置：

@Configuration public class ServiceContentNegotiationConfig implements WebMvcConfigurer { @Override public void configureContentNegotiation(ContentNegotiationConfigurer configurer) { // 1. 严格禁用路径扩展，避免网关未剥离后缀时的冲突 configurer.favorPathExtension(false) // 2. 禁用format参数，防止网关透传恶意参数 .favorParameter(false) // 3. 显式注册所有支持的vendor MediaType .mediaType("v1", MediaType.parseMediaType("application/vnd.company.v1+json")) .mediaType("v2", MediaType.parseMediaType("application/vnd.company.v2+json")) // 4. 设置默认MediaType为v2，体现向前兼容 .defaultContentType(MediaType.parseMediaType("application/vnd.company.v2+json")); } // 5. 添加Controller级别的MediaType校验 @ControllerAdvice public static class MediaTypeValidationAdvice { @ExceptionHandler(HttpMediaTypeNotAcceptableException.class) public ResponseEntity<Object> handleMediaTypeNotAcceptable( HttpMediaTypeNotAcceptableException e, HttpServletRequest request) { String accept = request.getHeader("Accept"); // 记录详细拒绝原因，供监控告警 log.warn("MediaType rejected for request {} with Accept: {}", request.getRequestURI(), accept); return ResponseEntity.status(HttpStatus.NOT_ACCEPTABLE) .body(Map.of("error", "Unsupported Accept header", "supported", Arrays.asList("application/vnd.company.v1+json", "application/vnd.company.v2+json"))); } } }

5.4 全链路ContentNegotiation健康检查

最后，为保障网关与服务的协同，需建立自动化健康检查：

@Component public class ContentNegotiationHealthIndicator implements HealthIndicator { private final RestTemplate restTemplate = new RestTemplate(); @Override public Health health() { try { // 测试网关是否正确重写v1 Accept头 HttpHeaders headers = new HttpHeaders(); headers.setAccept(Collections.singletonList( MediaType.parseMediaType("application/vnd.company.v1+json"))); HttpEntity<Void> entity = new HttpEntity<>(headers); ResponseEntity<String> response = restTemplate.exchange( "http://gateway/api/orders", HttpMethod.GET, entity, String.class); // 验证响应头Content-Type是否为application/json String contentType = response.getHeaders().getFirst(HttpHeaders.CONTENT_TYPE); if ("application/json".equals(contentType)) { return Health.up().withDetail("v1_negotiation", "OK").build(); } else { return Health.down().withDetail("v1_negotiation", "Expected application/json, got " + contentType).build(); } } catch (Exception e) { return Health.down(e).build(); } } }

将此健康检查接入Prometheus，当content_negotiation_health{type="v1"}指标为0时，立即触发告警，运维可在故障扩散前介入。

6. 最后分享：我在三次大型重构中沉淀的ContentNegotiation黄金法则

从业十年，我主导过三个千万级用户的系统重构，ContentNegotiation相关问题占API层故障的37%。这些血泪教训凝结成五条无需背诵、但必须刻进肌肉记忆的法则：

法则一：永远显式声明produces，永不依赖默认
@GetMapping("/api/users")这种写法是定时炸弹。必须写成：
@GetMapping(value = "/api/users", produces = MediaType.APPLICATION_JSON_VALUE)
理由：默认produces为空集合，意味着“支持所有MediaType”，这会让ContentNegotiation失去约束，任何客户端Accept头都可能命中，导致不可预测的序列化行为。

法则二：路径扩展（Path Extension）不是特性，是历史包袱
除非你维护一个必须兼容IE6的古董系统，否则在WebMvcConfigurer中第一行就写：
configurer.favorPathExtension(false);
我见过最惨的案例：某政务系统因.do后缀与Struts2遗留接口冲突，导致SpringMVC协商出text/html，而Struts2返回JSON，前端解析双重JSON字符串崩溃。

法则三：Accept头是契约，不是建议
当客户端发送Accept: application/vnd.api+json; version=2.0，你的服务要么完整支持（包括参数），要么明确拒绝（406），绝不能静默降级为application/json。降级看似友好，实则破坏API契约，让客户端无法感知自身版本过期。

法则四：网关与服务的ContentNegotiation策略必须文档化并双向验证
我们团队的做法是：

• 在Confluence建立《ContentNegotiation Strategy Matrix》表格，列明网关重写规则、服务支持MediaType、对应Controller的produces声明；
• 每次发布前，运行自动化脚本调用curl -H "Accept: xxx"遍历所有组合，验证响应Content-Type是否符合矩阵预期；
• 矩阵变更需双人复核，避免单点失误。

法则五：406错误日志必须包含Accept头原始值，且不可脱敏
曾因安全团队要求日志脱敏Accept头，导致线上406问题无法定位。最终妥协方案是：

• 在日志中保留Accept头的MediaType主类型（如application/json），但脱敏参数（如version=2.0）；
• 同时开启DEBUG日志开关，仅对特定TraceID输出完整Accept头，供紧急排查。

这五条法则没有一条来自官方文档，全部诞生于凌晨三点的线上故障现场。它们不追求技术炫酷，只解决一个朴素目标：让每一次HTTP内容协商，都成为可预测、可验证、可追溯的确定性过程。当你把ContentNegotiation从“配个配置就完事”的认知，升级为“API契约的生命线”时，你就真正掌握了SpringMVC的底层脉搏。