# URI 构造：从硬编码到契约级资源定位

```text
旧方案：硬编码 "/api/owners/" + id
冲突：context-path、反向代理、HTTPS、API Version 变化
后果：链接错乱、跨环境失效、契约漂移
```

在 REST 服务里，创建 Owner 后返回 Location 是基本动作。

但很多团队一开始图快，直接拼字符串。

我是老李，在深圳南山科技园做架构咨询时，见过一个团队因为硬编码 URI，在上了反向代理和 context-path 后，前端拿到的 Location 全部指向错误主机。

为什么硬编码 URI 在本地能跑，一到测试或生产就崩？

是继续拼字符串，还是把 URI 当作可组合、可编码的契约来构造？

如果选错，会不会让 API Version 升级时所有客户端链接静默失效？

# 01、故事

```text
周二 14:30→深圳南山科技园某研发中心→给 Petclinic 加创建 Owner 返回 Location→前端联调时链接全部 404
```

那天下午，会议室里前后端围着一块白板。

任务是给 Petclinic 的 Owner 创建接口补上 Location 响应头。

后端同学很快写完，本地 Postman 一测，返回 201，Location 是 /api/owners/17。

前端同学拿去联调，点开链接却全部 404。

测试同学催着要回归，运维同学说网关后面还有 context-path。

大家盯着代码里的 "/api/owners/" + id，一时没人说话。

> 南山午后雨未停，
> 白板写满旧路径。
> 本地能通线上断，
> 一字符里藏祸根。

# 02、问题

```text
需求变化：本地直连→网关+context-path+HTTPS+API Version
冲突：硬编码 URI 只认一种部署形态
后果：Location 指向错误主机、错误前缀、错误版本
```

硬编码 URI 失效的原因很直接：它把部署上下文写死了。

本地没有 context-path，网关不参与，协议是 HTTP，版本前缀可能不存在。

一旦上了网关，外部请求是 https://api.example.com/petclinic/v1/owners。

而服务内部看到的可能是 http://container:8080/owners。

如果代码里写死 "/api/owners/" + id，返回给客户端的 Location 就丢了 /petclinic 和 /v1。

影响不止是 404，还包括缓存键错误、HATEOAS 链接失效、OpenAPI 文档与实际不符。

可验证的验收标准是：同一份代码在本地、网关后、带 context-path、带 API Version 四种环境下，Location 都能被客户端直接访问。

> 路径写死一时快，
> 环境一变百处改。
> 契约不在代码里，
> 链接自然随风摆。

# 03、原理

```text
核心机制：UriComponentsBuilder 分层构造 URI，ServletUriComponentsBuilder 感知当前请求上下文，MvcUriComponentsBuilder 反向解析 Controller 映射
```

Spring 的 URI Building 能力分三层。

底层 UriComponentsBuilder 负责 scheme、host、port、path、query 的组装与编码。

中间层 ServletUriComponentsBuilder 能从当前 HttpServletRequest 中提取 scheme、host、port、contextPath、servletPath

。

上层 MvcUriComponentsBuilder 通过 Controller 方法映射反向生成 URI，避免手写路径字符串。

一个反直觉判断是：URI 构造不是字符串拼接，而是上下文感知的组件组装。

另一个反直觉判断是：即使你只写 path，不写 scheme 和 host，ServletUriComponentsBuilder 也可能帮你补全，但补全的依据是当前请求，而不是客户端看到的原始请求。

这意味着在反向代理后，如果没配置 ForwardedHeaderFilter，补全出来的 host 可能是内网容器地址。

> 组件分层各司职，
> 上下文里取真值。
> 莫把拼串当构造，
> 代理之后见虚实。

# 04、架构

```text
输入：HttpServletRequest + Controller 映射 + 业务 ID
→ 本模块：UriComponentsBuilder / ServletUriComponentsBuilder / MvcUriComponentsBuilder
→ 输出：可编码、可组合、可跨环境访问的 URI
边界：不负责路由转发，不负责鉴权，不负责客户端缓存策略
```

这一层位于 Controller 与响应头之间。

它接收当前请求上下文和业务资源 ID，输出标准 URI。

收益是消除硬编码，统一编码规则，支持 context-path 和反向代理。

代价是代码从一行字符串拼接变成多行构造器调用。

适用条件是所有需要返回资源定位的 REST 接口。

不适用场景是纯内部 RPC，或者客户端完全自行拼装 URI 且服务端不返回任何链接。

> 一层薄薄构造器，
> 隔开环境与代码。
> 输入请求与映射，
> 输出契约不掺沙。

# 05、第一版实战

```text
环境→配置→代码→启动→验证→V1
```

环境：JDK 17，Spring Boot 3.x，spring-webmvc 6.x，需按当前官方文档核验版本。

依赖：spring-boot-starter-web。

先写一个最简单的 V1，用硬编码返回 Location。

```java
@PostMapping("/owners")
public ResponseEntity<Void> createOwner(@RequestBody Owner owner) {
    Long id = ownerService.save(owner);
    return ResponseEntity
            .created(URI.create("/api/owners/" + id))
            .build();
}
```

启动应用：

```bash
mvn spring-boot:run
```

验证请求：

```bash
curl -i -X POST http://localhost:8080/owners \
  -H "Content-Type: application/json" \
  -d '{"name":"老李"}'
```

示例输出：

```text
HTTP/1.1 201
Location: /api/owners/17
```

本地直连时，这个 Location 看起来能用。

成功标准：本地 curl 能拿到 201 和 Location。

但 V1 没有任何上下文感知能力。

> 一行拼串看似巧，
> 本地验证刚刚好。
> 若问网关何处去，
> 代码摇头不知晓。

# 06、排查

```text
诊断树：Location 404→是路径错还是主机错→是 context-path 丢还是版本丢→是代理头没透传还是代码没感知
```

第一个问题：网关后 Location 指向内网地址。

现象：前端拿到的 Location 是 http://container:8080/api/owners/17。

怀疑：服务端用 ServletUriComponentsBuilder 时取了请求里的 host，而请求是网关转发来的内网地址。

检查：

```bash
curl -i http://localhost:8080/owners/17
```

证据：响应头里的 Location 确实是内网地址。

根因：反向代理没有配置 X-Forwarded-Host 或 Forwarded 头，服务端也没启用 ForwardedHeaderFilter。

修复：在网关透传 X-Forwarded-Host，并在服务端注册 ForwardedHeaderFilter。

第二个问题：context-path 丢失。

现象：应用配置了 server.servlet.context-path=/petclinic，但 Location 还是 /api/owners/17。

怀疑：硬编码路径没有包含 context-path。

检查：

```bash
grep -R "api/owners" src/main/java
```

证据：代码里写死了 "/api/owners/"。

根因：V1 用 URI.create 拼字符串，完全绕过 Servlet 上下文。

修复：改用 ServletUriComponentsBuilder.fromCurrentContextPath()。

**错误尝试：** 曾经手动在路径前加 "/petclinic"，结果本地直连又坏了。

> 排查先看响应头，
> 再看代理透传否。
> 莫要头痛医头脚，
> 根因总在上下文。

# 07、优化

```text
V1：硬编码 URI.create("/api/owners/" + id)
证据：网关后 404，context-path 丢失
V2：ServletUriComponentsBuilder + MvcUriComponentsBuilder
```

V2 改成从当前请求上下文构造 Location。

```java
@PostMapping("/owners")
public ResponseEntity<Void> createOwner(@RequestBody Owner owner) {
    Long id = ownerService.save(owner);
    URI location = ServletUriComponentsBuilder
            .fromCurrentRequest()
            .path("/{id}")
            .buildAndExpand(id)
            .toUri();
    return ResponseEntity.created(location).build();
}
```

这样 Location 会带上当前请求的 scheme、host、port、contextPath。

再进一步，用 MvcUriComponentsBuilder 反向解析 Controller 映射，避免手写 "/owners"。

```java
URI location = MvcUriComponentsBuilder
        .fromMethodName(OwnerController.class, "getOwner", id)
        .buildAndExpand(id)
        .toUri();
```

改完后，同一份代码在本地、context-path、网关后都能生成正确前缀。

> 从当前请求取上下文，
> 从映射方法取路径。
> 硬编码从此退场去，
> 环境变化不惊魂。

# 08、演进

```text
V2：上下文感知 + 映射反向解析
能力：Location 可跨环境访问，路径不再手写
遗留：API Version 仍需手动处理，OpenAPI 契约未联动
```

用 V1 同一组请求验证 V2。

本地直连：

```bash
curl -i -X POST http://localhost:8080/owners \
  -H "Content-Type: application/json" \
  -d '{"name":"老李"}'
```

示例输出：

```text
HTTP/1.1 201
Location: http://localhost:8080/owners/17
```

带 context-path：

```bash
curl -i -X POST http://localhost:8080/petclinic/owners \
  -H "Content-Type: application/json" \
  -d '{"name":"老李"}'
```

示例输出：

```text
HTTP/1.1 201
Location: http://localhost:8080/petclinic/owners/17
```

收益是 Location 不再依赖部署形态。

代价是代码稍长，且需要理解 Spring 的 URI 组件模型。

遗留问题是 API Version 前缀如 /v1 还没有统一处理。

> 环境变化不再怕，
> 链接生成有章法。
> 版本前缀仍未解，
> 契约之路还须拓。

# 09、洞见

```text
从现象到判断：URI 不是字符串，是契约
```

## URI 是接口契约的一部分

```text
硬编码路径→环境变化→契约漂移
```

URI 结构一旦被客户端依赖，就和字段名、状态码一样属于契约。

OpenAPI 或 API First 流程里，路径模板是设计产物，不是实现细节。

代码里手写路径等于绕过契约，必然漂移。

## 反直觉判断：上下文感知不等于客户端视角

```text
服务端请求上下文→内网地址→客户端不可达
```

ServletUriComponentsBuilder 取的是服务端看到的请求。

反向代理后，服务端看到的 host 可能是内网地址。

必须配合 ForwardedHeaderFilter 才能还原客户端视角。

## 反直觉判断：反向解析映射比手写路径更稳定

```text
手写路径→改名漏改→链接失效
```

MvcUriComponentsBuilder 从方法映射生成 URI。

Controller 路径改名时，链接自动跟着变。

手写路径则要全局搜索替换，容易漏。

## 编码是 URI 构造的隐形门槛

```text
未编码 ID→特殊字符→路径截断或注入
```

UriComponentsBuilder 默认对路径段编码。

手写拼接如果忘了 URLEncoder，遇到空格或斜杠就会出错。

> 契约不在文档里，
> 在每一次链接中。
> 构造若是不编码，
> 特殊字符起妖风。

# 10、系统落地

```text
入口：POST /owners 创建资源
→ 服务：OwnerService 保存并返回 ID
→ 本模块：UriComponentsBuilder 生成 Location
→ 存储：数据库保存 Owner
→ 未实现：API Version 统一前缀与 OpenAPI 联动
```

原来 Petclinic 的创建接口只返回 200 和 body。

本篇增加了 Location 响应头，并用 URI 构造器生成。

现在客户端能拿到可直接访问的资源定位。

下一篇缺的是把 API Version 前缀纳入统一构造，并与 OpenAPI 文档联动。

官方文档可参考 Spring Framework 文档首页：https://spring.io/projects/spring-framework

> 系统落地一步步，
> 先有链接后有路。
> 版本契约未闭环，
> 下篇再把前缀筑。

# 11、小结

```text
三问三答：为什么崩→环境变化；怎么选→上下文构造；选错后果→契约漂移
```

为什么硬编码 URI 在本地能跑，一到测试或生产就崩？

因为硬编码只认一种部署形态，环境一变就失效。

是继续拼字符串，还是把 URI 当作可组合、可编码的契约来构造？

应该用 UriComponentsBuilder 系列，从请求上下文和 Controller 映射构造。

如果选错，会不会让 API Version 升级时所有客户端链接静默失效？

会，因为路径前缀写死在代码里，版本升级时链接不会自动更新。

当前状态：Petclinic 的 Owner 创建已返回可跨环境访问的 Location。

> 三问三答已分明，
> 环境变化是根因。
> 构造当从上下文，
> 契约方能稳如金。

# 12、作业

```text
理解→实战→排障→架构判断
```

## 理解题：UriComponentsBuilder 和 ServletUriComponentsBuilder 的区别是什么？

UriComponentsBuilder 是底层构造器，不感知请求。

ServletUriComponentsBuilder 继承它，并能从当前 HttpServletRequest 提取 scheme、host、port、contextPath。

## 实战题：给 Petclinic 的 Pet 创建接口加上 Location，要求支持 context-path 和反向代理。

用 ServletUriComponentsBuilder.fromCurrentRequest().path("/{id}").buildAndExpand(petId).toUri()，并注册 F

orwardedHeaderFilter。

## 排障题：网关后 Location 指向内网地址，如何定位和修复？

先检查网关是否透传 X-Forwarded-Host，再检查服务端是否注册 ForwardedHeaderFilter。若都没有，补上即可。

## 架构判断题：API Version 前缀应该写死在每个 Controller 路径里吗？

不应该。版本前缀属于全局契约，应统一配置或由网关处理，避免每个 Controller 手写导致漂移。

> 理解构造分层次，
> 实战链接跨环境。
> 排障先查代理头，
> 架构判断莫写死。

# 13、升华

```text
工程结论：URI 是契约，构造是能力
```

URI 不是字符串拼接的副产品，而是接口契约的一部分。

用 UriComponentsBuilder 系列构造 URI，本质是把环境差异关进组件里。

硬编码省下的几秒钟，会在环境变化时加倍偿还。

下一篇将把 API Version 前缀纳入统一构造，并与 OpenAPI 文档联动，让契约从代码延伸到设计。

> 链接虽小见真章，
> 契约藏在路径旁。
> 构造若能知环境，
> 万变千改也不慌。

**系列项目：** Petclinic REST 服务，面向宠物医院前后端与第三方集成。

**已完成：** Owner 创建返回 Location，支持 context-path 与反向代理。

**本篇：** 用 UriComponentsBuilder 系列替代硬编码 URI 构造。

**下一篇：** API Version 统一前缀与 OpenAPI 契约联动。

我是老李，在深圳南山科技园做架构咨询时，见过一个团队因为硬编码 URI，在上了反向代理和 context-path 后，前端拿到的 Location 全部指向错误主机。

《SpringMVC7实战》第11招 URI不要到处字符串拼接

用 UriComponentsBuilder 重构 Petclinic 资源定位，解决 context-path、反向代理、HTTPS 与 API Versio

架构师

后端

开发工具

架构设计

URI构造从硬编码升级为契约级资源定位，解决context-path、反向代理及APIVersion引发的链接错乱。通过ServletUriComponentsBuilder与MvcUriComponentsBuilder实现上下文感知，确保Location跨环境可访问，消除契约漂移，并兼容网关部署。

代码解释

数据库

容器

路由

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

《SpringMVC7实战》第11招 URI不要到处字符串拼接-腾讯云开发者社区-腾讯云

《SpringMVC7实战》第11招 URI不要到处字符串拼接

《SpringMVC7实战》第11招 URI不要到处字符串拼接

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐