这个问题问到点子上了！在REST架构里，这类用来控制是否返回特定内容的布尔参数，行业里已经形成了不少通用的命名惯例，我结合你的具体场景给你梳理清楚：

主流的前缀选择 #

• include：这是最广泛被接受的命名方式，语义直白清晰——直接表达“是否包含指定内容”，完美匹配你场景里“控制是否返回地址”的需求。比如可以命名为include_address（蛇形命名）或者includeAddress（驼峰命名），只要和你的API整体风格统一就好。
• with：也是非常流行的选项，强调“附带返回某部分内容”，读起来很符合自然语言逻辑，比如with_address，就像说“获取建筑信息附带地址”。
• 补充：少数场景会用到expand，但这个更多用于关联资源的展开（比如把关联资源的ID展开成完整对象），如果只是同一个资源内的字段，include/with会更贴切。

针对你的场景的具体示例 #

以你的GET /buildings接口为例：

• 默认请求（不带参数）返回基础数据：

  [ { "name": "The Empire State Building", "floors": 102 } ]
  

• 当需要返回地址时，通过参数控制：GET /buildings?include_address=true，返回内容如下：

  [ { "name": "The Empire State Building", "floors": 102, "address": "20 W 34th St, New York, NY 10001" } ]
  

  如果你习惯驼峰命名，用includeAddress=true也完全没问题，核心是保持整个API的命名风格一致。

额外的实用建议 #

• 风格统一：整个API体系里尽量只用一种前缀，别这次用include下次用with，会增加开发者的理解成本。
• 支持多字段场景：如果后续需要控制多个可选字段的返回，建议改用逗号分隔的列表形式，比如GET /buildings?include=address,owner，这种比多个布尔参数更简洁灵活。
• 文档明确：不管用哪种命名，一定要在API文档里明确说明参数的作用、默认值（比如默认false不返回地址），避免开发者踩坑。

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