ASP.NET API GET方法传可选gender参数时返回id参数绑定错误

• 路由匹配逻辑和你的请求格式不匹配
  • ASP.NET Web API 默认路由模板为 api/{controller}/{id}，其中 id 段会默认绑定到控制器里带 int id 参数的 Get 重载方法。
  • 你当前访问的地址 http://localhost:61491/api/Employees/gender=female 缺少查询字符串必须的起始标识 ?，路由引擎会把路径中的 gender=female 整段识别为 {id} 对应的取值，尝试把这个字符串绑定到不可空的 int id 参数上。由于类型转换失败、参数不支持空值兜底，直接触发参数绑定错误，请求根本不会走到你编写的带 gender 参数的方法上。
• 无对应自定义路由规则
  • 你提供的web.config配置里没有定义匹配自定义gender参数的路由规则，现有默认路由完全无法识别直接拼在路径段里的键值格式，无法将参数传递到目标方法。
• 控制器方法存在路由重载冲突
  • 你的控制器中存在两个带GET动词的方法：一个是带 int id 参数的单条查询方法，一个是你写的带 string gender 参数的筛选方法。当路由错误匹配到前者时，参数绑定失败会直接中断请求，不会进入后续方法匹配逻辑去选择后者。

修正方案 #

• 改用标准查询字符串格式发请求：将访问地址修改为 http://localhost:61491/api/Employees?gender=female，此时路由会匹配无需传入id的GET请求，自动从查询串中提取 gender 参数绑定到目标方法。
• 如果希望使用路径式参数格式（如 api/Employees/gender/female），需要在Web API路由配置中新增一条优先级高于默认路由的规则，指定路由模板为 api/{controller}/gender/{gender}，将路径段和方法的gender参数做对应绑定。
• 注意：路径段是按顺序匹配路由模板的，不会自动拆分等号两侧的键值，所有带键值对的筛选参数必须放在以 ? 开头的查询串部分。

内容的提问来源于stack exchange，提问作者nnmmss