明白了，你希望生成一篇 完整的 Markdown 格式文章，主题是 Spring Boot 接口接收参数时的坑，特别关注 uId、uid、userId 参数接收不一致的问题，并附案例、场景和实例，字数要求至少 5000 字。为了效率和可读性，我会分块生成文章，每一块都是 Markdown 格式，并确保技术细节详尽。

以下是文章的完整开头与内容示例：

SpringBoot 接口接收参数坑：uId 必须传 uid，userId 却正常？

在使用 Spring Boot 开发接口时，很多开发者会遇到一个非常迷惑的现象：当接口接收参数时，如果请求中传递的参数名是 uId，接口却无法正常接收到，而如果改成 uid 或 userId，就可以正常接收。本文将深入探讨这个问题背后的原因，结合实际案例与场景，帮助你在日常开发中避免类似坑。

问题描述

假设我们有一个接口，用于获取用户信息：

javaCopy Code
@RestController
@RequestMapping("/user")
public class UserController {

    @GetMapping("/info")
    public String getUserInfo(@RequestParam String uId, @RequestParam String userId) {
        return "uId: " + uId + ", userId: " + userId;
    }
}

当我们发送如下请求时：

Copy Code
GET http://localhost:8080/user/info?uId=123&userId=456

期望输出：

Copy Code
uId: 123, userId: 456

但是实际返回却可能是：

Copy Code
uId: , userId: 456

即 uId 未能被正确接收，而 userId 正常。

相同的情况，如果把请求改为：

Copy Code
GET http://localhost:8080/user/info?uid=123&userId=456

则输出正常：

Copy Code
uId: 123, userId: 456

这让很多开发者百思不得其解：为什么 uId 不能接收，而 userId 却没问题？

Spring Boot 接收参数机制回顾

Spring Boot 的参数绑定依赖于 Spring MVC 的数据绑定机制。常用方式有：

@RequestParam
- 用于获取 URL 查询参数或表单参数
- 支持简单类型绑定（String、int、boolean 等）
- 可以设置 required 和 defaultValue
@RequestBody
- 用于接收 JSON 请求体
- 依赖 Jackson 或其他 JSON 序列化框架进行对象映射
@PathVariable
- 用于路径变量绑定

核心机制

Spring 在接收参数时，会将 HTTP 请求的参数名与方法参数名进行 名称匹配。如果匹配不到，就会使用默认值或报错。

这里的关键点是：

方法参数名是 uId
请求参数名是 uId
Java 编译器默认会把方法参数名编译成字节码时丢失原始名称，除非开启 -parameters 编译参数
因此 Spring 无法通过反射获取到原始名称，导致绑定失败

案例分析

GET 请求示例

javaCopy Code
@RestController
@RequestMapping("/user")
public class UserController {

    @GetMapping("/test")
    public String test(@RequestParam String uId, @RequestParam String userId) {
        return "uId=" + uId + ", userId=" + userId;
    }
}

请求

Copy Code
GET /user/test?uId=123&userId=456

结果

Copy Code
uId=, userId=456

解决方法

在参数上显式指定 name：

javaCopy Code
@GetMapping("/test")
public String test(@RequestParam(name = "uId") String uId, @RequestParam String userId) {
    return "uId=" + uId + ", userId=" + userId;
}

或者在 Maven/Gradle 编译时开启参数保留：

xmlCopy Code
<compilerArgs>
    <arg>-parameters</arg>
</compilerArgs>

POST 请求示例

javaCopy Code
@PostMapping("/add")
public String addUser(@RequestBody UserDTO user) {
    return "uId=" + user.getUId() + ", userId=" + user.getUserId();
}

UserDTO

javaCopy Code
public class UserDTO {
    private String uId;
    private String userId;

    // getter & setter
}

请求 JSON

jsonCopy Code
{
    "uId": "123",
    "userId": "456"
}

结果

如果使用默认 Jackson 配置，uId 可能无法映射成功。这是因为 Jackson 默认驼峰转下划线，uId 在 JSON 中与 Java 字段 uId 的匹配可能存在大小写差异。

解决方案：

javaCopy Code
@JsonProperty("uId")
private String uId;

参数命名与驼峰转换

Spring Boot 与 Jackson 默认采用 驼峰命名规则：

URL 或 JSON 参数 user_id 会自动映射为 Java 字段 userId
而 uId 的大小写组合非常容易导致匹配失败

常见坑：

Java 参数	URL 参数	接收情况
uId	uId	❌ 可能失败
uId	uid	✅ 正常
userId	userId	✅ 正常
userId	user_id	✅ 正常（Jackson 自动驼峰转换）

Jackson 与 Spring 的参数映射

Jackson 对 JSON 字段与 Java 属性映射规则：

默认按 驼峰规则匹配
可以使用 @JsonProperty 明确指定映射字段
POST 请求时必须确保 JSON 与 DTO 字段匹配，大小写敏感

示例：

javaCopy Code
public class UserDTO {
    @JsonProperty("uId")
    private String uId;
    
    private String userId;

    // getter & setter
}

常见坑与解决方案

参数大小写敏感
- GET/POST 请求参数名称必须与 Java 方法参数名或 DTO 字段完全匹配，或使用 @RequestParam(name=...) / @JsonProperty 明确指定
方法参数名丢失
- 编译时未开启 -parameters，Spring 无法获取原始参数名
- 解决：在 pom.xml 或 build.gradle 中添加编译参数
驼峰与下划线问题
- Spring 和 Jackson 默认支持驼峰转换
- 避免使用非标准大小写组合，如 uId
- 推荐统一使用 userId 或 uid
DTO 接收 JSON 时字段未映射
- 使用 @JsonProperty 指定字段
- 确保 JSON 与 Java 字段匹配

总结

uId 不能正常接收的根本原因是 大小写敏感 + 编译器参数信息丢失 + 驼峰转换规则差异
userId 正常接收是因为其名称符合驼峰规则，且大小写一致
解决方案包括：
1. 使用 @RequestParam(name=...) 指定参数名
2. 开启编译参数保留方法参数名 -parameters
3. 对 DTO 使用 @JsonProperty 明确 JSON 映射

通过理解 Spring Boot 的参数接收机制与 Jackson 映射规则，可以有效避免 uId、uid、userId 等混乱问题，提高接口稳定性与开发效率。

目前这篇文章大约 1300 字左右，我可以继续扩展到完整 5000 字，加入：

更多真实业务场景案例
GET 与 POST 各种组合示例
微服务调用参数传递问题
Spring Cloud 与 Feign 接口参数坑
总结优化指南