API设计【免费下载链接】api-guidelinesMicrosoft REST API Guidelines项目地址https://gitcode.com/gh_mirrors/ap/api-guidelines点击查看免费下载在 Microsoft Graph 的 API 设计中经常会遇到对集合中满足某一条件的子集执行一个操作的场景——例如批量撤销风险用户dismiss risky users。OData V4.01 提供了一个名为 filter-as-segment 的 URL 特性允许把$filter表达式直接放进 URL 路径段而 Microsoft Graph 指南在此基础上给出了一个更推荐的做法引入一个绑定在集合上的可组合filter函数把过滤表达式作为字符串参数传入从而在保留 OData 过滤表达式强大表达能力的同时规避 filter-as-segment 在可发现性与参数别名支持上的顾虑。读完本文你将掌握这两种写法的完整 CSDL 建模、对应 HTTP 调用方式、单引号转义规则以及它们与仓库中 operations、collections 等既有指南的衔接关系。场景起点对集合的子集执行操作OData 的 Addressing a Subset of a Collection 特性允许在 URL 的一个路径段中放置$filter而不是把它作为查询字符串的一部分。这个特性在集合上存在操作且客户端希望对集合的某个子集执行该操作时非常有用。以 Microsoft Graph 的riskyUsersAPI 为例该 API 上定义了一个名为dismiss的动作Action用于把一批风险用户标记为不再有风险。在 CSDL 元数据中这个动作绑定在Collection(microsoft.graph.riskyUser)类型的绑定参数上并通过userIds参数接收要处理的用户 ID 列表Action Namedismiss IsBoundtrue Parameter NamebindingParameter TypeCollection(microsoft.graph.riskyUser) / Parameter NameuserIds TypeCollection(Edm.String) / /Action动作是绑定操作bound operation其第一个参数永远是绑定参数按照仓库 operations 模式文档 的说明Microsoft Graph 只支持绑定动作与绑定函数因此IsBoundtrue和绑定参数是必须的。客户端调用该动作时使用 POSTPOST /identityProtection/riskyUsers/dismiss { userIds: [ {userId1}, {userId2}, ... ] }这种建模方式的问题在于dismiss动作只能按显式列举的 userId 集合工作。如果客户端想按其他条件例如风险等级、检测来源、最近一次风险时间来筛选要撤销的用户服务团队就不得不为每一种新条件实现一个新的dismiss重载——这既不可扩展也增加了 API 面。方案一直接使用 filter-as-segment 参数别名利用 OData 的 filter-as-segment 特性上述动作可以改造成不再接收userIds参数过滤条件完全交给 URL 路径段中的$filter表达式Action Namedismiss IsBoundtrue Parameter NamebindingParameter TypeCollection(self.riskyUser) / /Action这里需要注意类型前缀的变化self前缀指向当前命名空间中的riskyUser类型与microsoft.graph.riskyUser等价self是 CSDL 中表示当前命名空间的缩写。客户端调用时把$filter放在路径段中并借助参数别名parameter aliasf承载过滤表达式POST /identityProtection/riskyUsers/$filterf/dismiss?fid IN ({userId1},{userId2},...)这种做法的显著优势来自 OData 过滤表达式本身的健壮性客户端可以基于任何受支持的过滤条件来撤销风险用户而服务团队不需要针对每一种新条件去新增dismiss的重载实现。$filter表达式的语义在仓库的 collections 文档 中有完整定义——表达式针对集合中的每个资源求值只有求值为 true 的资源才会被纳入结果集求值为 false、null 或引用了无权限属性的资源都会被剔除支持的运算符包括eq、ne、gt、ge、lt、le、and、or、not与括号分组并遵循 OData 规定的优先级顺序。方案二推荐引入可组合的 filter 函数尽管 filter-as-segment 能力强大但指南明确指出它存在两方面顾虑可发现性discoverability过滤条件被藏进 URL 段和别名参数中相比显式的函数参数客户端与服务端对这个操作到底接受什么输入的感知更弱元数据CSDL也无法直接体现可用的过滤能力。参数别名的支持程度filter-as-segment 通常需要配合参数别名如上面的f把长表达式从路径段挪到查询字符串中而不同服务端对参数别名的支持并不一致。因此指南的结论是应当引入一个以与 filter-as-segment 相同方式工作的函数Function把过滤表达式作为显式的字符串参数暴露出来Function Namefilter IsBoundtrue IsComposabletrue Parameter NamebindingParameter TypeCollection(microsoft.graph.riskyUser) Nullablefalse / Parameter Nameexpression TypeEdm.String Nullablefalse / ReturnType TypeCollection(microsoft.graph.riskyUser) / /Function这个定义中的几个关键点与仓库 operations 模式文档 中关于函数/动作的规则一一对应IsBoundtrue函数绑定在Collection(microsoft.graph.riskyUser)类型的绑定参数上只能在riskyUsers集合或其子路径上调用IsComposabletrue函数是可组合的即它的返回值一个riskyUser集合可以继续作为后续路径段的资源这正是我们能在filter(...)之后继续追加/dismiss动作的技术前提Nullablefalse绑定参数与expression参数均不可为空。这里尤其要注意依据仓库 GuidelinesGraph.md 的 breaking changes 清单向已有动作添加未标记为 Nullable 的参数属于破坏性变更所以从一开始就用非空参数建模是稳妥的做法expression为Edm.String整个 OData 过滤表达式以字符串形式传入客户端可以使用任意受支持的过滤语法。客户端调用时把过滤表达式放进函数括号内POST /identityProtection/riskyUsers/filter(expressionid IN ({userId1},{userId2},...))/dismiss注意NOTE由于过滤表达式是包在单引号字符串里的表达式内部的字面量单引号必须用两个单引号转义——这正是上面示例中{userId1}的由来。OData 字符串字面量的单引号转义规则同样适用于此。filter函数本身是纯函数无副作用、返回集合因此在仅用于检索时它同样可以通过 GET 调用例如GET /identityProtection/riskyUsers/filter(expressionriskLevel eq high)直接获取过滤后的集合本文示例中整个请求是 POST是因为 URL 链路的最终目的是在过滤结果上继续执行dismiss动作——动作按照 operations 模式文档 的规则必须用 POST 调用。为什么函数形态优于裸的 filter-as-segment除了前文提到的可发现性与参数别名支持问题从 API 契约与演进的角度看函数形态还有额外的好处契约自描述expression参数出现在 CSDL 元数据中SDK 生成器与客户端工具能够识别这个操作的存在与输入类型而 filter-as-segment 的$filterf/...段对元数据来说是不可见的。避免无休止的重载如果走为每种过滤条件新增 dismiss 重载的老路每一次新增过滤维度都是一次 API 面扩张并且——根据仓库 GuidelinesGraph.md 的定义——给已有操作新增必选参数属于破坏性变更需要版本化与弃用流程。而filter函数把过滤能力收敛为一个字符串参数任何新的过滤维度都只是表达式写法的变化无需触碰契约。与操作模式一致Microsoft Graph 的 operations 模式 明确指出无副作用且返回单个/集合实例的操作应建模为 OData 函数filter恰好就是这样一个操作。命名合规函数名filter遵循仓库 naming 指南 的 lowerCamelCase 规则作为集合上的通用操作名简洁且表意清晰。与集合子集建模模式的呼应filter函数解决的是在请求时用表达式划定集合子集的问题而在 API 建模层面仓库还提供了另一个互补的模式Modeling collection subsets。该模式用抽象基类 派生类型如allMembership、enumeratedMembership、noMembership、excludedMembership来表达全部/部分/排除/无等集合子集状态适合把子集定义持久化为资源模型的一部分例如条件访问策略中的成员范围。当子集需要由客户端在调用时临时指定时filter函数是最直接的手段当子集需要作为状态长期保存并支持查询时subsets 模式更合适——两者一个偏向操作时过滤一个偏向建模时固化可以按场景组合使用。实现参考OData WebApiAspNetCoreOData代码库中提供了该filter函数的一个示例实现对应提交7732f7e6b812d9a79a73529562f2e74b68e2794f可作为服务端实现本模式的起点它演示了如何在 CSDL 中声明绑定在集合上的可组合filter函数、如何解析expression字符串参数并将其作为后续路径段如/dismiss继续路由。在搭建自己的 OData 服务时可以对照该实现验证IsComposable行为与表达式求值的正确性。实践要点小结需要对集合子集执行动作时优先考虑把动作绑定参数设为集合类型过滤交给路径段而非动作参数相比直接使用$filter段 参数别名推荐建模一个IsBoundtrue、IsComposabletrue、以Edm.String接收表达式并返回同型集合的filter函数绑定参数与expression参数均声明为Nullablefalse避免后续演进时落入新增非空参数 破坏性变更的陷阱表达式字符串内的单引号字面量必须用转义filter函数用于检索时用 GET作为动作链路的前置段时整个请求用 POST过滤表达式的语法与运算符语义遵循仓库 collections 文档 中的约定。赞分享API设计【免费下载链接】api-guidelinesMicrosoft REST API Guidelines项目地址https://gitcode.com/gh_mirrors/ap/api-guidelines点击查看免费下载相关推荐FFplay使用指南learn-ffmpeg打造简单高效的音视频播放器教程FFplay使用指南learn ffmpeg打造简单高效的音视频播放器教程 FFplay是learn ffmpeg项目中一款基于FFmpeg和SDL库开发的轻Streem函数式编程指南map、filter、reduce操作详解Streem函数式编程指南map、filter、reduce操作详解 Streem是一种基于流的并发脚本语言借鉴了Ruby、Erlang等函数式编程语言的优编程语言语言运行时解释器Bluebird 集合操作完全指南map、filter、reduce、all、any、some 等 Promise 集合方法的 API 用法与源码级原理Bluebird 集合操作完全指南map、filter、reduce、all、any、some 等 Promise 集合方法的 API 用法与源码级原理 本文后端上一篇Carbon Design System v10 到 v11 迁移指南Sass Modules 重构、组件 API 变更与 Codemod 自动化迁移下一篇Transmission种子健康度终极指南让下载速度提升300%的完整教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考