pipe-ner-server/pipe-network-service/docs/adr/0009-retain-parameter-names-and-explicit-mvc-binding-names.md

---

status: accepted

Retain parameter names at compile time and name MVC binding annotations explicitly

供水 GIS 图层 /waterSupply/gis/map/features、流量监测分页 /waterSupply/monitoring/flow/page 等接口运行期返回 500：Name for argument of type [java.lang.String/long] not specified, and parameter name information not found in class file either.。

根因（经 spring-webmvc 5.3.39 MockMvc 最小复现验证，与是否被 CGLIB 代理无关）：Spring MVC 对未显式命名的 @RequestParam/@PathVariable，先靠 -parameters 保留的反射形参名，再靠调试局部变量表（-g:vars，Maven 默认开、裸 javac 默认不开）兜底；两条路都拿不到名字时，参数绑定直接抛异常。本工程两个 pom 都未开 -parameters，一旦运行时类未带局部变量表即必现。

决策（A+B 双保险）：

• A（构建兜底）：根 pom.xml、pipe-network-service/pom.xml、zksy-system/pom.xml 的 maven-compiler-plugin 统一开启 <parameters>true</parameters>；pipe-network-service 的编译器插件由不支持该选项的 3.1 升到与根一致的 3.8.1。实测开启后即使 -g:none 也能正常绑定。
• B（代码规范）：新增/在维护的控制器显式写 @RequestParam(value="x")/@PathVariable("x")，不依赖编译产物。本轮先覆盖供水（web/controller/WaterSupply，17 个）与排水（web/controller/drainage，8 个）共 25 个控制器、397 处；其余历史控制器由 -parameters 兜底，显式命名另行排期，避免跨团队大 diff。
• 禁止 @RequestParam Map/ MultiValueMap 形式补名（Spring 对 Map 形参走整表注入，写名反而报错），脚本已内置跳过。

新增控制器的评审检查项：绑定注解必须带显式名；CI 构建不得关闭 -parameters。