此笔记位置已失效,请从目录继续阅读。
全书导读
本书讨论一个经常被HTTP接口外观掩盖的问题:多个互不控制、各自演进的服务,怎样在网络不可靠的条件下长期合作。超媒体在这里不是给JSON多放几个URL,而是让消息携带链接、表单和必要元数据,客户端在已约定的格式与业务词汇内,运行时发现地址和动作。
全书前两章建立REST、Web、极晚绑定、消息与语义边界;第三至七章分别回答设计、客户端、服务端、数据与工作流问题,最后一章讨论采用顺序。附录包括原则速查、书目、格式目录和HyperCLI命令用途。正文配方默认按“问题—方案—取舍”理解;只有工具命令附录按操作参考处理。
阅读时必须区分四个层面:HTTP方法提供什么语义、实现是否兑现;消息能否解析、业务词汇能否理解;请求已受理、业务是否完成;重试目标状态不再变化、是否仍存在并发冲突。书中2022年的示例报文和规范草案并非当前标准的完整摘录,已在相应卡中保留必要边界。
身份采用版权页的October 2022 First Edition与First Release 2022-10-14,OPF日期同为2022-10-14;Copyright 2023是版权年,不将它误写成首次出版时间。ISBN为978-1-098-10674-4。
全书主线
本书把“可独立变化”分配到稳定契约与运行期信息两层。协议、媒体格式与语义词汇是共同理解的基础;具体地址、可用动作和输入约束可随当次状态返回。客户端需要有解释这些信息的能力,服务端则必须把能力、失败和兼容承诺真实发布出来。
flowchart TD
A[协议 格式 词汇的稳定边界] --> B[消息携带链接与表单]
B --> C[客户端发现并验证动作]
B --> D[服务端公开能力与失败]
C --> E[条件写 缓存 查询范围]
D --> E
E --> F[共享状态 进度 作业与任务]
F --> G[有界重试 撤销 人工恢复]
G --> H[小步采用并观察收益]
这条路线逐层增加条件,而非逐层消除所有耦合。运行期发现地址仍需要业务词汇;幂等写仍需要稳定资源身份和实现承诺;多服务共享文档仍不构成分布式事务;代理包装旧服务仍可能看不到隐藏副作用。理解这些边界,才能从目录中选择适合当前问题的配方。
序言:沿链接发现下一步
互联网应用依赖客户端、服务器、网络与开放协议;超链接让用户从当前页面看到可走的方向。链接降低导航学习成本解释这种导航体验为何影响超媒体API的设计:调用者应获得下一步的线索,而不是预先掌握所有远端地址。序言的行业比例和个人经历用于背景,不作为本轮核验的当前统计;对本书的推荐不替代后续配方的机制和条件。
原书依据 · 1 处
前言:配方的使用方法
本书围绕在开放网络上设计、消费和维护服务接口收集配方,主要提供问题、消息与伪代码示例、解决思路和取舍,而非从零实现教程。按问题而非技术选配方说明为什么读者需要把问题与环境分开判断。
每项配方由Problem、Solution、Example、Discussion和Related Recipes组织;配方讨论保留方案取舍帮助避免把某个建议误当成唯一答案,模式通过关联共同生效则提示独立阅读与组合部署是不同层面。
前两章建立历史与设计基础,第三至七章依次讨论设计、客户端、服务、数据与流程,最后一章给出采用建议。附录补充原则、文献、标准与HyperCLI操作。读者可按眼前问题检索,也可先读基础和结语形成整体认识;组织级方案还需要把配方转成自己的检查清单。HTTP细节、具体API编码、数据治理和流程工程另有推荐材料,不能把本书当作这些领域的完整实现指南。
字体约定、示例授权、联系方式和致谢已阅读,属于出版辅助信息;未把推荐书名或人物名单虚构成技术知识卡。
第一部分导引:先理解可恢复性
这一部分用Christopher Alexander关于熟练木工的题辞引入基本观念:步骤留出纠错余地。它不提供软件回滚协议,后两章将用网络、协议和超媒体模型建立实际设计基础。
原书依据 · 1 处
第01章 RESTful Web API导论
RESTful Web API在这里是一种让独立服务长期协作的设计:不把本地对象直接搬上网络,而是以约定消息、动作和词汇建立边界。REST的约束、Web开放链接、极晚绑定分别贡献架构属性、低参与成本和运行期演进能力。
定义资源节点、链接、表单与可供性,把当前可执行动作放入消息,解释通用消息如何隔离本地对象。 超媒体应用把消息、动作和领域词汇组合起来:通用消息格式承载信息,链接和表单提供下一步动作,共享词汇赋予字段与动作业务含义。三者分别解决能否解析、怎样交互、怎样理解的问题;只有JSON数据字段而没有可发现动作,不能提供这里所说的运行期交互能力。 详见超媒体连接三要素。
超媒体把资源视为信息节点,用URI连接节点。普通链接选择目标,表单还描述需要输入并传递的数据。服务在响应中返回可用链接和表单,客户端选择并执行它们,便逐步推进应用状态。浏览器能访问不同网站而不改自身源码,正是通用接口的效果;业务语义仍需要词汇和使用者理解。 详见链接表单驱动状态。
可供性是环境向行动者提供的可行动机会。在API中,响应里的链接和表单就是可供性:它们使搜索、提交、修改等动作可被发现和执行。与仅在外部文档描述某URL相比,把动作随当前状态返回,可以让交互选择与当前环境一起变化。 详见可供性提示下一动作。
网络间传递通用消息,而不是直接暴露本地对象或函数,可以把通信规则与实现方式分离。格式和协议构成稳定外壳,内部功能与内容可以持续变化;即使某种承载格式退出生态,也无需因此重做整个通信协议。这里的收益来自封装边界,并不表示消息里的业务含义自然就能被理解。 详见消息隔离本地模型。
从REST的属性与约束到Web最小能力、自由链接,再到极晚绑定,说明为何网络服务需支持空间和时间上的独立变化。 REST是网络软件的架构风格,通过成组约束诱导系统属性,而不是端点命名清单。客户端—服务器、无状态、可缓存等约束服务于可扩展、通用接口、独立部署与中介可见性。设计时应先明确需要的性能、可靠性、可修改性等属性,再评价约束组合;不能只凭使用HTTP判断已经获得这些效果。 详见REST以约束诱导属性。
最小能力原则要求选足以完成任务的最简单技术。Web用通用链接和表单让任何文档指向其他文档,不要求双方预先协调,从而降低参与和重新组合信息的成本。它要求保留必要能力;简化到无法表达业务动作,同样不符合原则。 详见最小能力降低门槛。
极晚绑定把具体交互细节的决定推迟到运行时,使系统运行期间仍能替换或修改局部。网络始终在运行,每次部署本来就是在线改变整体系统;因此客户端应在已约定的协议和消息规则下读取当次动作信息,减少在编译时绑定具体地址与步骤。 详见极晚绑定支持演进。
通过信息架构和魔法字符串讨论共同含义,再以未知用例、陌生使用者和几十年寿命说明开放接口的长期责任。 字段名是需要人理解的“魔法字符串”:两个服务都能解析telephone,并不保证它们对字段含义达成一致。领域词汇应同时明确含义、组织关系和交互规则,即ontology、taxonomy、choreography;跨独立代码库保持一致语义,才让通用消息真正可复用。 详见共享词汇弥合语义差。
开放网络上的服务可能被未曾见面的使用者组合,用于最初未预想的问题,并持续远超原定寿命。接口因此需要携带使用所需上下文、保持词汇一致,并支持长期独立演进。设计目标不是预测所有用例,而是用低门槛、明确约定和可组合动作容纳未来用途。 详见为未知使用者守约。
第02章 用超媒体思考与设计
网络编程面对的不是一台共同控制的机器,而是各自部署、可能不可达且随时间演进的参与者。超媒体设计先约定稳定通信和语义边界,再让具体地址、动作参数及流程在运行期出现。客户端承担适应性,服务承担稳定承诺;数据和工作流也必须遵守这个边界。
以异构机器通信和信息架构建立先验设计:约定网络级消息规则,同时保留节点内部技术自由。 异构机器不必统一内部语言和工具;可另约一套网络级控制语言,交换描述通信方式的元消息。代价是要实现网络协商,收益是各节点能独立优化与部署。超媒体采用同样思路:先约定消息规则,再在运行期传送动作细节。 详见网络采用独立控制语言。
信息架构把数据组织成可理解、可导航的信息环境,让使用者知道身在何处、找到了什么、周围还有什么、下一步会怎样。API可用本体描述意义、分类组织对象、交互规则描述动作;这种组织既服务于人,也为机器选择动作提供稳定边界。 详见信息架构解释位置。
比较URL/对象绑定与协议/格式绑定,继而解释元数据解释器、机器语义边界及由客户端组合工作流。 客户端与服务必须共享某些稳定规则。直接绑定URL和内部对象结构能快速生成专用客户端,却容易随服务变化失效;绑定协议和消息格式,则能把地址与内容留给消息表达。协议、格式、语义profile共同提供较稳定的边界,但客户端仍须实现这些边界并理解业务词汇。 详见客户端绑定稳定抽象。
客户端可一次实现表单解释器,再从响应中读取目标地址、HTTP方法、编码、字段及约束,按当次元数据构造请求。这样地址和字段次序变化时不必重写每个请求。机器客户端还需要把字段映射到本地已有数据;只认识表单结构并不能推导新字段的业务值。 详见运行期解析请求元数据。
人会理解表单含义、寻找输入值并处理错误,机器没有这些免费能力。语义profile预先约定问题空间内所有可能字段与动作,客户端再据此把运行期表单字段映射到本地数据。新增机器不理解且无法供值的必填字段仍可能破坏交互;超媒体并不消除语义契约。 详见机器交互需要语义边界。
把业务步骤硬编码到客户端,会使步骤增删和顺序变化成为客户端变更。另一种方式是读取服务返回动作并逐项执行;当流程跨多个独立服务时,还可由客户端持有声明式步骤和起始地址,通过各服务运行期动作完成任务。此时业务应用存在于客户端的组合与完成目标中,单个服务无需知道全流程。 详见客户端掌握工作流目标。
说明长期服务的可修改性问题,以兼容承诺、添加新能力和运行期发现绑定维持稳定接口。 已发布接口的非破坏性演进遵守三条规则:不删除已有元素、不重定义含义、新增元素可选。新增必填参数应放到新动作,保留旧动作;新动作本身也不能变成旧客户端必须执行的步骤。承诺还应说明客户端如何容忍未知内容;仅发布新版文档不足以保证所有使用者及时迁移。 详见兼容演进三条承诺。
服务接入若依赖人反复查找、读文档和手工集成,任一依赖变化都会重启这段成本。find and bind通过统一服务名称和描述元数据,把发现及集成推进到运行期。它需要规范化可发现描述与可解释接口,并非只把一个URL放进注册表就自然完成业务适配。 详见发现绑定自动化接入。
从多副本与远程数据假设出发,把数据视为动作证据,区分内外模型、读写诉求和检索/存储引擎。 将数据视为远程意味着不能控制其存储结构、访问者和可用性,也不能假定手中副本与别人一致。数据提供者负责本地完整性并记录读写来源;消费者应准备更新被拒绝、获取新副本和处理来源不可用。缓存可改善性能,但需要最新数据时仍可能回源;跨源更新还必须判断部分成功是否需要撤销。 详见远程数据副本有边界。
数据可视为动作留下的证据:创建和更新改变属性,多次动作形成可查询的历史。对HTTP服务,完整请求和响应的元数据及消息体是直接证据;HAR、message/http或application/http可记录它们,再转成便于查询的表示。存储优化可以变化,但不应损害证据质量。 详见数据是动作证据。
内部数据模型、对象模型、资源模型、外部表示模型不是同一东西。API出现user与job-status资源,不说明后端必然有同名表;稳定的是外部属性与读写承诺。将内外模型映射隔离,才能更换文件、数据库或消息存储而不迫使客户端跟随变更。 详见存储与外部表示分离。
分布式读取主要影响可感知延迟与可用性,可用本地缓存或显式异步接口降低影响;长查询应表达202 Accepted及后续状态。写入更关键的是完整性:多个目标中一个失败,可能要求撤销已成功写入,因此应尽量缩小单次写入的目标数。读优化不等于写一致性方案。 详见分开处理读写约束。
数据库查询通常针对库内事实得到确定结果;信息检索查询按条件寻找匹配文档或其指针,适合分布式来源及索引。读多的网络接口可以内部采用检索引擎,写入另选适合完整性和吞吐量的存储。具体引擎属于实现细节,接口不应暴露它;书中对产品流行度的描述只代表2022年语境。 详见检索与数据库查询有别。
比较编排和协作,提出task/job通用动作及声明式文档,再覆盖共享状态、可观察性、时间上限和错误求助。 集中编排在一个文档中规定流程,由引擎调用服务,易验证、监控,却增加中心依赖和耦合。协作式流程由独立服务各做自己的动作涌现,替换与异步处理更灵活,但难观察全局进度。选择应考虑步骤、分支、控制和可观察性;不能仅凭没有中心节点就推定整体可靠。 详见编排协作各有代价。
超媒体工作流把独立服务动作称为task,把一组task组成job。task提供执行、重做、撤销、取消;job还支持从断点继续、从头重启和整体取消。文档声明需要完成什么,服务保留内部实现自由;撤销若涉及下游服务,必须把相应影响一并处理,不能只恢复本地值。 详见任务作业用动作组合。
独立服务不宜通过共享数据库或同一内部模型协调;可用结构化媒体文档传递状态,以预先约定的profile限定属性与动作。流程还需要可定位的进度、可干预的继续或取消操作、maxTTL时间上限及无法自动处理错误时的人工求助路径。共享外部文档不要求共享内部实现。 详见工作流共享状态文档。
第二部分导引:配方的组合
模式不会孤立存在,它的作用受周围其他模式的支撑条件影响。前言中的模式通过关联共同生效已保留这一观点;本部分继续按设计、客户端、服务、数据和流程展开,阅读时需要追踪具体依赖,不能把目录当成互不相关的技术清单。
原书依据 · 1 处
第03章 超媒体接口设计
本章把前两章的设计方向变成配方。协议、媒体结构、词汇、语义profile及运行期控件逐层分离;接着补齐不可靠网络下的重试、状态传递和撤销;最后让消息与接口在不破坏旧客户端的前提下演进。以下按2022年原书说明设计,不把历史示例当成当前标准的完整规范。
媒体类型支持稳定互操作,说明格式发现、多个格式、安全扩展和自建类型的长期维护成本。 长期互操作先选择并公开稳定媒体类型,使客户端能绑定消息规则。服务宜支持不止一种格式,让客户端发现和选择;优先考虑可嵌入超媒体并支持安全扩展的类型。自建格式还承担注册、文档、示例工具与长期社区支持成本,不能只按当前实现方便选择。 详见注册媒体类型促互通。
用HTML容器和直接JSON对象对比消息结构与业务内容,区分结构正确及内容有效。 结构化媒体类型规定与具体业务字段无关的容器规则,例如一组li位于ul中;增加email字段仍可符合原结构。必须区分“消息结构正确”与“业务内容有效”:能解析消息,不意味着业务必填字段齐全。这里的structured指预先定义的领域无关消息结构,不是说JSON语法本身没有结构。 详见结构与业务内容分层。
采用公开字段词汇,映射内部术语,并治理优先来源、同义词和新词发布。 外部接口采用公开定义的词汇,并发布字段及定义来源;如givenName代替局部fname,可降低他人理解成本。内部历史命名可通过防腐层映射,不必因此修改存储。治理应明确优先词汇源、限制同义词,并在找不到合适词时统一发布新词;词汇还应摆脱具体SDK或平台依赖。 详见公开词汇隔离内部命名。
用ALPS把本体、分类和动作写为语义profile,区分profile与含URL/协议细节的API定义。 语义profile列出属性、聚合对象和动作,描述问题空间的规则,供设计期及运行期共享。ALPS可用ontology、taxonomy、choreography标签组织元素,用safe、idempotent、unsafe表达动作语义;具体URL、方法和状态码属于接口实现定义,应留在OpenAPI等文档。响应可公开profile URI,已发布档案若需破坏性修改,应另发新URI并保留旧版。 详见语义档案描述问题域。
把动作及输入约束写进HTML/Collection+JSON响应,以运行期控件支持上下文、位置和工作流变化。 服务需要调整交互地址、输入规则或工作流,而旧客户端不能随每次调整重写请求时,可把这些细节放入响应控件。
响应把动作地址、方法、字段及校验规则嵌入控件,客户端按已约定格式解释它们。例如表单可声明givenName和familyName必填、telephone匹配十位数字,以及提交地址和编码;字段、权限上下文和流程步骤可随运行期状态变化。前提是双方支持同一格式及领域词汇;新增机器无法提供的语义输入仍需协调。 详见嵌入控件表达当前动作。
扣款POST响应丢失导致业务结果不确定,再用客户端URI、条件PUT及ETag解决重复创建/覆盖问题。 账户扣除50积分的POST发出后,客户端没有收到响应,存在至少两种可能:请求未到服务端,或已扣款但成功响应丢失。客户端无法只凭超时判断业务是否发生;盲目重发非幂等请求可能再次扣款。这是网络结果不确定性造成的重复业务风险,而非简单的错误状态码问题。 详见扣款超时结果不明。
针对扣款超时结果不明代表的不确定写入问题,书中优先采用客户端确定资源URI的条件PUT设计:创建时用If-None-Match: *,更新时用If-Match携带上次ETag,前置条件不满足返回412。重试仍指向同一资源并受版本条件保护,不能仅把增量扣款POST改名为PUT就宣称幂等;操作本身还须具备可重复语义。 详见条件PUT保护写入。
比较现有表单、专用导入导出、共享引用三种服务间状态传递及协调成本。 一个服务被外部客户端纳入更大流程时,需要让状态可以跨独立服务传递,而不把调用者锁在专属会话中。
服务要能参与外部组合,应尽量接受完整输入、完成动作、返回结果,避免要求预先建立专属会话。小状态直接填接收方表单;大而复杂的集合可用importState/exportState;共享可访问资源也能按引用传递。后两者需提前约定数据形状、格式和词汇。文件上传表单与传递URL指针不同,不能因示例并列就混同机制。 详见状态传递三种接口。
区分网络幂等和操作幂等,分析批量百分比更新失败后重试风险,用替换值及验证条件支持重放。 商品目录用updatePercent=.05逐项涨价,处理中途故障会留下部分已更新、部分未更新的状态;若成功后响应丢失,客户端同样不知道已完成多少。重新执行整个百分比更新,会让已处理商品再次涨价。即使请求使用PUT,业务消息仍是增量操作,方法名不能弥补这个重复作用风险。 详见涨价批处理重放风险。
对涨价批处理重放风险,把消息改为productId,currentPrice,newPrice。服务只有在当前价格仍等于currentPrice时才写入newPrice,否则跳过该记录;重放不会再次叠加百分比。书中也给出仅传productId与newPrice的替代方式,适合直接重复设置最终值的语义。比较与写入应按完整业务条件实现,不能只靠PUT字样保证安全。 详见替换值使批处理可重放。
可重试既要求网络方法的约定,也要求操作消息的业务语义。GET、PUT、DELETE具备幂等方法语义;实际更新还应使用替换值及必要验证条件,避免“增加1”或“涨5%”式重复累加。幂等表示重复作用不再增加预期状态效果,并不保证每次响应码相同;条件更新重放也可能因条件已改变而被拒绝。 详见安全重试有两个层次。
区分旧值条件回写与特殊恢复命令,讨论历史保留和下游多资源撤销依赖。 已提交的更新或删除后来需要撤回时,接口必须提供安全恢复路径,并考虑并发修改和下游影响。
单资源更新可以再发条件PUT写回旧值,前提是保留旧值并确认资源未被他人修改。删除没有通用UNDELETE方法,可设计undoDelete或rollback动作,用原地址及版本信息恢复;服务需保留可恢复历史。若一个动作影响多个资源和下游服务,撤销还需覆盖所有影响,不可把本地回写当成完整回滚。 详见撤销操作需保存历史。
用扩展集合、平行属性、外层容器承载新旧消息,保留严格schema验证的兼容风险。 既有消费者仍在使用旧消息,而新需求要求增加属性或改变字段形态时,需要让新旧表示并存。
扩展响应时保留旧字段:标量phoneNumber变为多值需求时新增phoneNumbers,name拆分时保留name并增givenName、familyName。预留名称—值集合可容纳附加属性,外层message容器可并列承载新旧表示。输入也应兼容旧格式;严格拒绝未知字段的客户端校验仍会破坏这些扩展策略。 详见消息扩展只增不替换。
把兼容三规则应用到参数、动作和分叉迁移,说明所有可观察行为均可能成为用户依赖。 运行中的API需要改变参数、动作或业务限制时,应先判断能否保持现有消费者的调用承诺。
修改已发布接口时,不删除、不重定义、新增可选。新增搜索regions参数应有默认all,缺失时服务使用默认值;若新流程需要salesRep等必填输入,应增加独立动作并保留原processOrder。不可避免的破坏性修改应分叉新接口并安排新旧并行迁移,旧测试应继续检查兼容性;所有可观察行为都可能被使用者依赖。 详见接口变更保留旧路径。
第04章 超媒体客户端
超媒体客户端是能够根据服务响应中的链接、表单和元数据继续行动的程序。它并非没有预先知识:必须理解HTTP、消息格式及业务词汇,才知道哪些数据和动作有意义;可变的是这些动作此刻在哪里、用什么方法、需要什么输入。本章把这些层次分别处理,以减少服务变更对消费者的冲击。面向机器的客户端没有浏览器前的人替它判断,因此还必须显式验证消息、记住交互状态,并知道何时停止。
地址是第一层变化。把URL收拢成命名变量、外部配置,再进一步只保留稳定起点,从运行时响应发现其余地址,可以逐步降低迁址成本。配置本身仍有更新滞后,真正动态的地址需要服务下发。逐步外置服务地址保留这条渐进路径。地址之外,客户端还要能直接使用HTTP;SDK封装可能漏掉新能力,也可能把多次远程调用藏在一个看似普通的方法里。保留直接HTTP能力解释怎样保留协议访问和网络成本的可见性。
第二层是消息结构。客户端如果为每个业务函数单独写代码,服务多一个动作便可能要求发布新版客户端。消息中心设计改为统一解析数据、链接和表单;服务在同样结构中发布新控制时,通用引擎可以使用这些控制。这个能力依赖真正的结构化消息,普通JSON并不会自动告诉机器怎样操作。客户端绑定消息结构说明代码职责怎样改变。第三层是业务词汇:doAdd为何表示添加、id标识什么,需要客户端和服务共享语义profile。用词汇契约识别动作把ALPS的数据、动作、输入与返回目标串起来;运行时核对语义契约进一步说明收到响应时如何核实服务支持的词汇。书中的profile头字段是当时的协商草案及双方约定,不能预设任意服务都实现。
运行时解析也需要边界。客户端先用Accept表示可读格式,再依据实际Content-Type把消息交给对应转换器,形成内部模型;不支持的格式应报告问题。按媒体类型分派解析解释这种分派与转换。服务缺少profile时,schema标识可作为辅助路由信息,但对象schema通常比词汇和消息格式变化更频繁,维护成本也更高,详见模式标识辅助消息路由。找到消息还不等于找到动作:响应内的ID、NAME、REL和TAG有不同范围和唯一性,响应元素的四类标识说明它们怎样帮助机器识别表单和数据。
识别完成后,客户端应使用控制中提供的地址、HTTP方法、输入编码和参数,而非再回到硬编码调用。不同格式的H-Factor能力不同,因此能下发多少细节,也决定客户端必须自行掌握多少规则。按超媒体控制发请求用编辑表单说明这条调用路径。旧服务完全不提供控制时,可依据人工文档集中整理链接和表单,让同一个执行引擎消费,但静态副本会产生同步责任,角色权限也要单独考虑;这是本地补充链接与表单的边界。
数据验证分发送前与接收后两面。服务可随响应发送丰富输入描述RID,包含必填、只读、正则、范围和枚举;客户端按新规则验证,而非永久固化旧规则,见输入规则随响应更新。发送正文前还应区分“能解析”与“业务字段有效”,使用可靠的schema或定制验证器;简单表单转JSON的办法不应套用于任意嵌套命名约定,见发送前校验请求正文。接收响应则按协议、结构、值三层检查本次任务所需内容,避免因无关扩展误拒整个消息,见入站消息分三层检查。这种容忍以安全为界:只允许已知字段进入自己的运算,检查语法及跨字段业务关系,再从过滤后的副本计算,详见仅处理过滤后的输入。
最后,多个服务并不知道客户端的完整工作目标,临时应用状态应由客户端维护。记录请求与响应历史,再提取选定状态变量,可让客户端判断接下来做什么;请求地址与重定向后的地址也应分别保存。客户端保存交互状态给出这种记忆结构。自主操作还须有明确目标:退出型目标达到条件便停止,维持型目标持续观察并调节;两者都需要预先设定的评估规则和由本地掌握的退出或告警条件。用目标驱动自动客户端把状态、动作、目标与环境联系起来。这并不是自动学习,而是把人的控制意图明确编码后交给机器可靠执行。
第05章 超媒体服务
超媒体服务要长期维持外部承诺,同时允许内部代码、数据和部署持续变化。本章的接口设计把两件事分开:媒体类型、词汇与业务动作形成可理解的契约,运行时消息则携带当前位置、可用操作和偏好。服务的可靠性也属于这个契约:发现、健康、错误和依赖故障处理都不能留给客户端猜测。
最小的位置承诺是至少一个稳定起点。消费者可以保存它,服务迁移后仍维持旧入口并引导新位置;其他URL由响应继续提供,不要求每次调用都重新经过起点。承诺稳定服务起点说明如何通过文档与home链接公布。位置稳定之外,还要避免把内部对象或数据库表直接当成接口。外部可以是一个扁平ToDo集合,内部却分布在不同对象中,维护映射与一致性是服务自己的责任,见外部模型独立设计。
表示和动作都应单独设计。表示是发给消费者的消息视图:同一电话数据可在CSV里摊平为列,在超媒体里变成关联资源;不同格式不必复制同一内部形状。显式映射外部表示保留格式选择、映射和演进规则。动作则按消费者要完成的工作组织,一个“拒绝合同”动作可包住多个内部更新,消费者不用记住步骤次序,见动作契约遮蔽内部流程。把流程藏进接口并不会自动获得事务安全。外部参数也应保留演进空间,例如以有名字的选项代替固定布尔状态,再由映射层转换到内部值;外部枚举保留演进空间解释以后加入pending等状态的条件。
为了让消费者选择正确表示,服务应公开可支持的方法、媒体类型、请求编码、语言及profile等能力。即使只有一个可选值,也值得明确发布。OPTIONS可用于询问能力,独立GET偏好资源则可以缓存,避免重复探测成本;发布可缓存偏好资源特别区分两者的缓存语义。协商时,主动方式由消费者发送Accept偏好,服务决定并用Content-Type说明结果;响应式方式则先列候选,消费者再请求,增加一次往返且需要约定机器选择细节。内容协商的两种选择说明这些边界,不把偏好误当作保证。
共享理解还需要明确词汇。数据字段名、表单名、链接关系和查询动作都属于词汇,文档必须解释它们表示什么以及在不同消息格式中可能出现在哪里。词汇描述覆盖数据与动作把词汇含义和媒体类型的结构解析区分。schema负责对象或文档结构,语义profile负责共享数据及动作词汇,SDD服务定义文档负责具体API实例,三者职责不同,见区分词汇与模式文档。服务可使用service-desc关系公布OpenAPI等定义入口;多种接口风格可对应多份定义,详见公开服务定义入口。再以service-meta和APIs.json汇集文档、入口、格式、安全、维护者等资产,形成可发现的目录,见用元数据汇集API资产。书中工具、媒体类型约定及规范状态均按2022年背景理解。
可用性信息与失败信息也是正式接口。健康资源以pass、fail、warn等值回答接口当前能否正常服务,可带必要的依赖检查与版本;它应保持轻量,配合GET缓存和ETag,而不是对每个订阅者大量回调或暴露内部调试。健康检查保持轻量保留原书参考草案及其适用边界。错误则需稳定的类型、简明解释与本次发生信息;书中使用RFC 7807的Problem Details,并允许媒体类型已有的错误结构优先,见错误也是正式响应。状态码足够时不必增加复杂错误正文,详细堆栈也不应外泄。
部署在变,服务发现也应随运行状态更新。实例启动时向注册表登记地址、支持词汇与媒体类型,运行时保活,正常停止时注销;崩溃不能及时注销则依赖心跳超时淘汰。每个实例和版本应可分别被找到,注册服务完整生命周期解释这一生命周期。写入流程也可能有不必要的等待:如果客户端提前生成客户、账户和销售记录ID,就可消除“等待服务返回ID”这一依赖,可能并行创建。服务仍须验证ID,真正的先后业务约束及失败恢复不会因此消失,见客户端预分配资源标识。
网络带来更重要的结果歧义:POST转账500元后没有响应,不等于没有转账;成功响应丢失后重复请求可能再次转账。转账响应丢失的歧义保留这个具体资金问题。对应办法是为同次创建使用可重复识别的资源地址与幂等写入,并用条件头表达创建或更新前提;用幂等创建消除重复写入同时指出HTTP方法名不能代替业务副作用去重。
服务依赖故障时,应针对每项读写依赖预备重试、静态或动态备用、延后入队和明确失败等退路,见为每项依赖准备退路。这些恢复能力宜在本地实现,不能又变成新的外部必需依赖。重试必须评估动作幂等、错误类型、频率和次数,不能把超时当成服务未执行的证明,见重试必须理解动作语义。延后入队更不是隐形实现细节:支付返回202时,库存和配送可能已经承诺,必须让调用方协调后续步骤。支付入队牵连其他步骤描述风险,入队响应公开处理进度解释公开受理状态和监控位置的解法。
最后,旧服务未必能采用上述契约。可用代理在消费者和旧服务间翻译协议、表示及词汇,并补充所需控制。小范围定制代理、企业级转换和语义profile代理的成本不同;尤其语义翻译受到模糊术语和组织知识影响,不能把格式转换完成视为业务含义已对齐。以语义代理接入旧服务说明怎样限定代理职责,以及为何它可能增加延迟和长期维护负担。
原书依据 · 22 处
- 超媒体服务 · 查看原书依据
- 超媒体服务 · 查看原书依据
- 超媒体服务 · 查看原书依据
- 超媒体服务 · 查看原书依据
- 超媒体服务 · 查看原书依据
- 超媒体服务 · 查看原书依据
- 超媒体服务 · 查看原书依据
- 超媒体服务 · 查看原书依据
- 超媒体服务 · 查看原书依据
- 超媒体服务 · 查看原书依据
- 超媒体服务 · 查看原书依据
- 超媒体服务 · 查看原书依据
- 超媒体服务 · 查看原书依据
- 超媒体服务 · 查看原书依据
- 超媒体服务 · 查看原书依据
- 超媒体服务 · 查看原书依据
- 超媒体服务 · 查看原书依据
- 超媒体服务 · 查看原书依据
- 超媒体服务 · 查看原书依据
- 超媒体服务 · 查看原书依据
- 超媒体服务 · 查看原书依据
- 超媒体服务 · 查看原书依据
第06章 分布式数据
分布式数据接口的任务并不等于远程暴露数据库。它应让消费者以业务动作和稳定消息工作,同时处理网络不可靠、并发冲突、查询规模与长期模型变化。
若客户端直接依赖存储引擎和查询语法,更换底层技术就容易破坏接口。
数据接口应承诺“更新客户”“查逾期账单”等业务能力,避免要求调用方提交数据库连接、表结构或存储引擎查询。外部表单表达客户需要的输入,由内部转换成存储操作;这样更换存储技术时可以保留接口承诺。
查询也优先提供具名链接或参数化表单。新增必填参数会增加兼容负担;有合理默认值时可保持可选。专门建设查询引擎本身,才是需要公开数据语言的另一种职责。 详见以业务动作隐藏存储。
幂等写表示相同请求重复执行,目标资源仍处于同一预期状态;并不保证每次响应相同。网络故障可能发生在写入之前,也可能只是成功响应丢失,客户端无法仅靠超时区分。稳定资源标识加替换式PUT,使重发无需变成第二次新增。
这是一项接口与实现共同兑现的承诺,不能只换HTTP方法就让业务副作用自动幂等。重试应有上限,持续失败记录并停止;并发写还需要条件写保护资源版本。 详见幂等写应区分丢响应。
条件写是在修改前核对资源版本,防止旧快照覆盖他人新修改。创建固定URL资源时用If-None-Match: *;更新时把先前取得的ETag放入If-Match。前提不成立就拒绝本次写入。
发生版本冲突后,要重新GET并结合最新内容调整修改,不能无条件覆盖。若前次请求已经成功、只是响应丢失,原条件重发可能被拒绝,客户端仍需核查实际状态;这与幂等写应区分丢响应并不矛盾。书中部分报文混写ETag/If-Match、412短语,本文保留其条件写机制,不把示例逐字当协议规范。 详见条件写保护资源版本。
业务输入跨越人员、地址等多个实体时,接口需要支持完整操作而不泄露内部关系。
一次业务写入可以携带多个内部实体所需字段,例如人员与地址;调用方只提交一个平面消息,由接口或服务拆成实际存储操作。成功响应再提供“增加地址”等后续动作。
这隐藏了实体关系,却不意味着多次内部写入天然具有原子性。实体分组提示可以帮助转换,但不能成为客户端依赖的存储结构承诺。人工输入过长时,可改为分阶段工作文档收集后提交。 详见平面消息隐藏实体关系。
简单查询可约定?name=value&city=value表示各字段“包含”条件的合取,既容易由表单生成,也不暴露底层SQL。=解释为包含是本接口约定,不能假定所有HTTP接口如此。
实现要定义空值、重复同名参数与大小写规则;例如空输入不应无意成为严格过滤。复杂查询语言塞入单一URL参数,可能触及长度、保留字符、编码、安全及模型耦合问题;需要更强语言时可用查询语言封装为媒体类型。 详见用简单查询承载筛选。
只有结果列表时,调用方难以判断查询质量、是否被限量以及如何改进。
查询响应除结果外,还可返回执行时间、执行时刻、返回条数、估计总数、状态、建议与重放链接,帮助调用方判断结果是否被限量、是否太宽以及如何调整。少量信息可随响应,较多时链接独立元数据资源。
应按消费者需要选择字段,避免暴露实际SQL、内部数据源或调试信息。q-status等是本书使用的自定义命名,需文档化,并非注册HTTP头或通用标准。 详见查询元数据帮助修正。
数据响应没有记录时,需要区分合法零匹配与请求处理失败。
状态码说明请求是否被正确处理,不能仅凭“没有数据”决定:
| 情形 | 响应含义 |
|---|---|
| 合法集合筛选零匹配 | 200与空集合 |
| 请求某个既存资源却不存在 | 404 |
| 查询参数或语法无效 | 适当4xx并提示修正 |
| 请求有效但存储或服务失败 | 适当5xx |
代理可把上游“空集合返回404”的行为转换成自己的稳定集合契约,同时隐藏内部故障细节。 详见空集合按请求语义响应。
接口需要强查询能力,却又不能随查询引擎更换而整体改写时,可以隔开语言消息与实际存储。
需要SQL、GraphQL等强查询能力时,把查询当作带媒体类型的请求消息,由接口负责转换到实际引擎,而非把接口直接等同于某引擎。Content-Type说明查询语言,Accept说明结果表示,二者可以独立。
例如书中以Content-Type: application/sql提交查询并创建查询资源;查询与结果是两个不同资源。支持更多语言仍需编写转换器并承担语义兼容成本。书中application/prs.*是其2022年示例中的自定义标识,不构成现行注册状态承诺。 详见查询语言封装为媒体类型。
服务只负责修改记录的一部分时,写回过程中容易丢掉自己不认识的数据。
只处理自己理解的字段,并不等于删掉其余字段。读取整条记录后修改电子邮件,再写回时应保留未知及未修改部分,避免破坏记录完整性,也让来源新增字段时消费者仍能工作。
这适用于双方约定的整记录读改写模式;提交仍须遵守来源提供的表单和并发条件。Must Ignore是“忽略语义、保留传递”,不是允许未知内容绕过写入安全校验。 详见未知字段保留往返。
服务依赖远端数据时,网络延迟与故障会降低可用性,完全绕过缓存又会增加负载。
缓存需要供需双方配合:提供方声明可缓存范围与新鲜期限,消费方遵守,并按用途提出可接受的新鲜度。静态列表可缓存较久,易变数据应缩短期限;准备编辑时尤其需要重新验证。
典型配置Cache-Control: private, max-age=600表达私有缓存与期限;no-cache要求使用前验证,不能理解为禁止存储。选择接受旧副本的策略应限于业务允许的读取。还要考虑Vary所指的协商维度,避免把错误语言、身份或表示的副本回放。书中缓存报文有简化之处,部署时需按实际协议规则确定组合。 详见缓存契约权衡新鲜度。
生产中的数据模型需要增加字段或回退版本时,严格模式可能迫使所有消费者同步升级。
显式字段位于固定模式中,隐式字段放入预留的名称值集合,例如nvp:[{name:"middleName",value:"Seymore"}]。新增数据先放扩展集合,可减少同步修改所有消费者模式的压力;回退服务版本时也能保留已收集的新数据。
统一访问函数先找显式字段,再找扩展集合,使字段以后升格为显式字段时调用方式保持一致。代价是读写规则更复杂,隐式字段的名称和值同样必须验证。此模式主要用于内部建模,外部仍应采用稳定消息格式。 详见显隐字段支持模型演进。
无法修改远端用户存储时,可在本地保存新增属性并用远端资源URL作为关联键,读取时再合并。新增字段应有独立名称,如workEmail,避免与远端email产生来源歧义。
关联不会建立跨服务事务或共同完整性约束。远端失联可按契约用缓存或默认值;404不能直接证明永久删除,不能贸然清除本地历史。保留历史、标记失联或清理孤儿记录,应按本地用途决定。 详见关联键扩展远端数据。
数据集持续增长时,无界查询返回会拖慢接口及其依赖服务。
数据接口应有默认最大返回量,检查调用方提供的值,并优先把限制传到存储查询。只在接口拿到完整结果后截断,虽然减少对外载荷,却无法避免上游查询、传输和内存代价。
总量限制决定本次查询最多选取多少条,分页大小决定每次展示其中多少条;例如总限1000、每页100,不是只查100条。修改限制或截断结果后,应在元数据中说明实际返回数、总量估计与截断状态。 详见限制总量不同于分页。
局部编辑代理可对外只暴露地址字段,却在内部保存完整人员响应及ETag。收到地址修改后,把字段映射回持有的完整记录,携原版本条件交给来源验证;不能把未展示字段丢掉。
代理表示与来源表示分别维护自己的ETag、URL和标识映射,二者不能混用。来源写入冲突要正确传回;来源缺少代理承诺字段时可返回502并隐藏内部拓扑。此模式是未知字段保留往返在中间服务上的另一种实现。 详见透传代理保存完整快照。
这些办法互相补足:隐藏存储与关系降低长期耦合;消息往返和条件写保护已知与未知数据;查询元数据、限制和缓存使调用者知道结果范围与时效。透传代理和本地扩展能组合他方数据,却不会自动统一各方完整性规则,因此不能把“一个外部资源”误当成“一个内部事务”。
第07章 超媒体工作流
超媒体工作流把独立服务临时组合成完整解决方案。其前提是服务共享一套可发现动作和标识约定,而不是彼此了解实现。任务是单个动作,作业是可并行的一组任务;顺序依赖要由作业之间连接表达。
相互独立的服务要安全拼成工作流,需要一致的动作与状态协作规则。
可组合服务把动作完整描述成表单:目标URL、方法、媒体类型和输入。任务支持执行、幂等重复与撤销;作业支持从断点继续和从头重跑,后两者不是同一操作。所有任务还共享状态资源。
作业ID关联整次工作,任务ID标识单步,随请求与响应传递;本书correlation-id/request-id命名属于需团队约定的非标准头。撤销未执行任务应是无害操作,以便某任务失败或超时时取消作业并统一撤销各任务;这依赖服务真实实现可重复、可逆承诺,并不等于获得分布式原子回滚。 详见可组合服务的动作契约。
共享状态是承载一次作业业务输入与结果的独立HTTP资源,不是让任务共同依赖一张内部数据库表。每个任务从中读取所需字段填表,并把结果以幂等更新写回;结束后归档。它与进度资源只报告执行分工不同。
调价示例保存currentPrice与updatedPrice,先核对当前价再写目标价,而不只保存“上涨百分比”,这样重复应用不会不断叠加。共享字段语义仍需事前约定;单靠共享URL与PUT不保证并发任务更新原子性。 详见共享状态独立成资源。
简单、变化少且不需定制的流程,可以在一个稳定服务接口后用代码调用其他服务。内部替换税费计算等依赖,不必改变外部承诺。
原书用Promise.all并行调用入职相关服务,前提是任务没有固定先后依赖;依赖链不能靠并行语法抹去。代价是流程变化也要经历编码、测试与部署,变体多时容易出现大量一次性实现。 详见代码编排适合稳定流程。
流程多且经常变化时,反复用通用代码处理HTTP和表单会提高交付成本。
工作流DSL把HTTP请求、查找表单、填入共享状态等重复细节收进有限指令,让流程作者专注连接任务。典型HyperCLI片段是REQUEST WITH-FORM cartCheckout WITH-STACK,从共享栈填入并提交发现的表单。
限制语言能力能减少错误空间,但不适合所有复杂判断。shell配合curl、jq也能实现编排,灵活性更高,同时需承担解析与错误处理。选DSL取决于流程变化频率和组织维护能力,书中HyperCLI语法仅为该工具示例。 详见专用脚本降低编排成本。
声明式工作流文档描述作业、任务、共享状态、标识与管理动作,由理解词汇的执行器决定如何完成。把描述与执行代码分开,允许改进引擎而不反复改写流程文档。
文档应保持描述性;把if/else、变量判断等大量塞进作业文档,会使其重新变成命令式语言。业务判断留在任务内;确实需要命令式控制时,采用专用脚本降低编排成本或代码。 详见声明文档分离执行策略。
RESTful JCL把任务作为单个动作,把作业作为能并行执行的一组任务;有固定先后依赖的任务要拆成多个作业,成功后依次衔接。引擎提供继续、重启、取消和成功/失败出口,并监视作业与任务最大时限。
作业文档管理的列表、筛选、创建、修改、删除,应与执行动作分开。先实现可组合服务的动作契约,再考虑通用引擎;自建控制系统成本高,不能因文档简单就低估执行与故障处理成本。 详见作业控制分开并行与顺序。
每次作业都可有独立进度资源,记录作业和任务标识、状态、起止时间、时限与必要消息,并提供刷新链接和新鲜度信息。调用者据此了解执行到哪里,而业务输入结果放入共享状态独立成资源。
进度不是内部跟踪日志,也不应随意放入重启、回滚等管理入口,避免与真正的编排控制冲突。完整HTTP报文可能泄露敏感数据,诊断细节应受访问控制,公开进度只保留必要反馈。 详见进度资源只报告执行。
当一次响应有太多可能动作,可返回常用动作及一个related入口,另一个资源按当前数据、服务、流程和身份上下文列出完整可用动作。客户端找不到目标动作时再跟随该入口。
这减少每个响应重复携带大量表单的成本,但代价是额外往返;不应把所有动作都藏掉。动作列表会随上下文变化,不能把旧列表当永久授权。 详见相关动作资源按需展开。
把所有动作都移到额外资源会增加查找往返,可用最近访问入口补足常用路径。
服务可记录最近访问链接,在响应中返回少量MRU入口,帮助消费者发现常用动作,也减少为寻找动作而多请求一次related资源。可按服务或用户维护固定长度历史。
返回前要按当前权限与服务状态过滤,过去可用不代表现在可用。通常仅保存并返回URL即可,不应试图从头部推导用户意图;简短链接比完整表单成本低。 详见最近使用链接减少查找。
WIP是可持久保存、反复修改和分享的工作文档,适合多方在数小时或数天内逐步收集输入。创建后可读取、更新、取消、转交,最后由有权者提交给正式处理。
例如入职资料分员工、访谈、背景核验与合同逐步补齐。更新阶段尽量接受任意局部输入,最终提交再检查完整性;状态、负责人、到期日可用于筛选待办。它与部分保存与最终提交不同,专门覆盖长期、多页、多人的收集过程。 详见工作文档承接长期输入。
大列表需要逐步浏览时,不能假定总页数或任意页号都能低成本计算。
分页接口提供first、previous、next、last、select以及exit/home等语义入口,消费者跟随实际返回的URL。首页可省略previous,尾页省略next;昂贵或难算的last也不必强求。
列表可仅返回摘要与详细项链接,按需计算下一页。直接跳第N页可能要求计算完整大列表;过滤后快照可稳定导航,但必须先付全量构建成本。页大小与总查询限制是两层控制。 详见分页沿可用链接导航。
复杂表单一次填全容易出错,机器客户端尤其难以修正多个相互关联的错误。
部分表单提交把“保存已填数据”和“开始业务处理”分开。客户端可每次提交一个字段,服务校验后保存并返回含已填值的新表单,直至最终提交或取消。
动作分为partialSubmit、refreshSubmit、resetSubmit、cancelSubmit与finalSubmit;重置清空重来,刷新只取当前状态。最终提交仍可校验跨字段依赖并返回纠错信息,不意味着所有字段必填。原书用GET演示保存过程,不能据此把有持久化副作用的GET当通用协议惯例。 详见部分保存与最终提交。
当最终目标只由客户端掌握时,服务需要按客户端选择提供状态反馈。
状态观察让客户端决定目标状态,服务只提供可观察变量与可调用动作。例如楼层控温程序选择温度传感器及恒温器,而照明程序选择运动传感器及灯开关,二者复用同一服务。
先获取可观察项,再创建每个消费者独有的选择资源,后续响应包含其选中值,直到更新或清空。相比长查询参数,独立选择资源便于复用,但双方须记住并传递URL,也要按身份限制可见项。书中watch相关关系与偏好是应用约定。 详见状态观察由客户端定目标。
复杂查询过长或重复执行成本高时,可先保存查询定义,再通过稳定资源入口重用。
将长查询放在请求体里创建查询资源,再以URL重新执行并取得结果,避免每次传超长URL,也便于缓存读取结果。查询定义、当次结果与管理入口要区分。
列表、筛选、修改、删除、分享管理查询集合;owner、tags、最后执行时间等帮助管理。重放既可能取既存结果,也可能按保存条件重新计算,接口必须讲明并返回缓存契约。共享查询还需决定编辑权限,必要时让使用者复制后修改。 详见存储查询区分执行与管理。
耗时工作可先返回202 Accepted,表示已接收,尚未证明业务完成。响应给出延迟状态资源、刷新间隔、状态和完成/失败链接;客户端随后GET查看进度,再去最终资源取结果。
初次确认甚至可以早于实际开工,因此接口必须事前说明哪些动作可能延迟。取消能力取决于底层动作能否撤销;涉及写入不能只删追踪记录就算取消。完成后的追踪文档可保留用于核查。 详见接受响应给出追踪资源。
自动重试只适用于重发仍安全的请求。连接丢失或部分服务端故障可能是暂时的;客户端请求错误通常要先修正,不能无差别重发所有4xx/5xx。HTTP方法语义还需底层实现兑现。
选定退避或随机等待策略,限制次数和等待量;每次尝试记录警告,耗尽后报告最终失败。串行步骤的等待会累加,必须受任务与作业总时限约束。重试是短期遮蔽故障,不能代替排查持续坏链路。书中退避数字与分类有简化,核心是有界等待与防止同时重试加剧负荷。 详见重试须幂等且受时限约束。
底层没有撤销动作时,接口可把已执行动作及必要历史按contextId持久记录,再用公开反向操作撤回,例如删除刚创建的资源。撤销还要检查适用时间和调用者是否具备反向操作权限。
这适合影响明确的简单CRUD,不意味着跨服务恢复到精确旧状态。时间窗口只能缩小风险,不能证明无人依赖新状态。多服务副作用不清楚时,可考虑延时撤销在提交前取消;不能把本地反向调用冒充全局事务。 详见直接撤销受历史与权限约束。
延时撤销先把变更置于短期等待,而非立即提交;若用户在窗口内取消,就丢弃待执行请求,底层从未看到原变更。典型过程是排队五秒、期间允许取消,窗口结束才执行。
它降低撤回已提交副作用的难度,却给每次支持撤销的写入增加固定延迟,层层叠加后可能显著拖慢流程。适合能容忍延迟的批处理与排队工作;开始执行后不能再假定可安全取消,更不保证多处写入原子完成。 详见延时撤销在提交前取消。
无法自动修复的工作流错误,应交给明确负责的人处理。告警至少带工作流说明、进度、共享状态和相关错误证据的受控链接,使处理者可以决定继续、重启或取消,而不是只看到一句失败。
作业描述中预先记录联系渠道,事后将事故归档并定期复盘,用于发现反复故障与修正设计。报告须限制私密数据与内部跟踪暴露;已有事故平台可承担路由,不必自行重造完整告警系统。 详见人工求助携带可恢复上下文。
持久队列把接收与处理解耦,可快速确认并等待后台执行;集群增加处理器消化积压,也可让单机故障时其他处理器继续服务。二者能在公共接口后引入。
排队等待同样消耗作业或任务时限;若消息常在处理前超时,需检查处理能力。消息必须自描述、共享状态独立,任务可以并行,扩容才有基础。队列与集群并不自动保证恰好执行一次或跨节点一致性,仍依赖可组合服务的动作契约。 详见队列缓冲集群扩展处理。
已有服务不满足工作流契约而又暂时无法替换时,可以用代理补齐,但必须检查隐藏副作用。
工作流代理可补齐共享状态读写、表单、关联标识与执行/重复/撤销动作,把旧服务接入编排。只读校验或纯计算较易包装:重复计算不引入外部副作用,撤销只需清理共享状态结果。
写服务的困难在于代理看不到隐藏的依赖写入;删除自己创建的资源,不一定撤回工单、日志等连带变化。优先只读服务;只有掌控旧服务并能证明重复与撤销安全时才包装写动作。代理还增加故障链路,宜作为过渡而非永久掩盖不兼容。 详见工作流代理优先只读服务。
这些模式分属不同层面:WIP与部分提交负责收集输入;状态观察让客户端决定目标;延迟响应与进度资源负责可见性;共享状态与作业控制负责执行配合。重试只能修复部分暂时错误,撤销受实际副作用约束,求助则承接自动化无法判定的情况。队列和集群改善接收及处理能力,不能替代这些语义契约。
原书依据 · 21 处
- 超媒体工作流 · 查看原书依据
- 超媒体工作流 · 查看原书依据
- 超媒体工作流 · 查看原书依据
- 超媒体工作流 · 查看原书依据
- 超媒体工作流 · 查看原书依据
- 超媒体工作流 · 查看原书依据
- 超媒体工作流 · 查看原书依据
- 超媒体工作流 · 查看原书依据
- 超媒体工作流 · 查看原书依据
- 超媒体工作流 · 查看原书依据
- 超媒体工作流 · 查看原书依据
- 超媒体工作流 · 查看原书依据
- 超媒体工作流 · 查看原书依据
- 超媒体工作流 · 查看原书依据
- 超媒体工作流 · 查看原书依据
- 超媒体工作流 · 查看原书依据
- 超媒体工作流 · 查看原书依据
- 超媒体工作流 · 查看原书依据
- 超媒体工作流 · 查看原书依据
- 超媒体工作流 · 查看原书依据
- 超媒体工作流 · 查看原书依据
第08章 结语:按收益渐进采用配方
采用配方首先是判断当前问题和合作范围。按协作范围安排落地解释为什么章节顺序不能直接变成交付顺序;统一模式名促进复用则指出共同名称可以让原本分散的实践进入团队讨论。
新服务可先统一少量格式和设计约束,随后再处理可重试、可逆和可扩展等需要双方理解的行为。客户端应尽量降低对单一服务的依赖,服务端则公开定义、词汇、健康与错误等元信息;两章需要配合阅读。共享存储限制配方适配限制了数据配方的迁移前提。
流程章节把前面各类配方组合成超媒体驱动的声明式协作;采用传统流程平台时可能需要翻译其表达,宜从简单场景开始。既有服务的改造由小步改造先验证收益约束目标与步幅。透传代理可以包装仍有价值的旧服务,却也引入额外层和代价,不能因为“现代化”标签就默认采用。
结语列出书站、示例、ALPS目录和后续内容作为2022年时的资料入口,本轮不假定所有链接与外部服务仍可用。最后的行动建议是用真实问题检验这些配方,并在不足时有据调整,而不是一次性替换全部系统。
附录B:进一步阅读
附录B提供建筑模式、超媒体、感知、信息架构、API、系统思考与软件架构等方向的书目。书目帮助回溯观点来源和继续阅读,但列出书名并不意味着本轮已阅读那些作品。这里逐条登记原始出版信息,不凭书名补造内容卡;具体被引用的思想以本书实际展开的章节为准。
附录D:HyperCLI操作参考
HyperCLI把HTTP请求、超媒体表示解析、响应历史和本地变量放进同一个命令行环境。启动或批量运行超媒体脚本用于开始交互或重放脚本。工具语法以2022年附录为范围;本轮未安装工具、调用示例站点或执行授权。
配置与临时变量分开管理、栈保存当前任务的变量与保存与恢复变量栈分别管理配置、临时对象和持久化范围;配置命名OAuth令牌再把命名授权配置与具体请求分开。
按语义链接定位请求地址决定请求目标,明确HTTP请求参数职责分清方法、查询、体与协商头,由表单元数据构造请求则读取服务给出的表单元数据。响应调试由查看响应历史排查交互和按路径选择响应内容承接。
不同媒体类型需不同解析族:读取CJ控件、读取HAL链接与内嵌资源、读取SIREN动作与实体、读取WSTL状态转移描述、按表示类型选择解析命令。这些命令体现结构约定,并不赋予客户端未知业务语义。用退出条件控制脚本和查看插件与工作目录补充脚本控制与本地扩展。
表格中CONFIG SAVE的描述重复写成Loads,部分格式的“计划支持”又与后面的命令表不完全一致;这里保留历史语法并说明不确定处,不把排版问题猜成经过验证的现今行为。
原书依据 · 17 处
- 附录D:HyperCLI操作参考 · 查看原书依据
- 附录D:HyperCLI操作参考 · 查看原书依据
- 附录D:HyperCLI操作参考 · 查看原书依据
- 附录D:HyperCLI操作参考 · 查看原书依据
- 附录D:HyperCLI操作参考 · 查看原书依据
- 附录D:HyperCLI操作参考 · 查看原书依据
- 附录D:HyperCLI操作参考 · 查看原书依据
- 附录D:HyperCLI操作参考 · 查看原书依据
- 附录D:HyperCLI操作参考 · 查看原书依据
- 附录D:HyperCLI操作参考 · 查看原书依据
- 附录D:HyperCLI操作参考 · 查看原书依据
- 附录D:HyperCLI操作参考 · 查看原书依据
- 附录D:HyperCLI操作参考 · 查看原书依据
- 附录D:HyperCLI操作参考 · 查看原书依据
- 附录D:HyperCLI操作参考 · 查看原书依据
- 附录D:HyperCLI操作参考 · 查看原书依据
- 附录D:HyperCLI操作参考 · 查看原书依据
尾记:封面獴与自然史
封面动物Galidictis grandidieri的分布狭窄,偏远栖地让研究者难以抵达;尾记介绍体形、条纹、食物与繁殖记录。夜行习性避开白天高温保留活动时间与高温的关系,单配与繁殖季节不同区分配偶关系、繁殖时段和未知寿命。文中的濒危与栖地状态属于该版说明,本轮未用它替代当前保护名录。插图来源、设计署名与字体信息属于制作资料,不承担API设计论证。
原书依据 · 2 处
跨章综合
稳定性来自选对共享层。第一、二章把协议、媒体格式、语义profile与具体URL、内部对象和存储模型分开;第三至五章再分别落实外部词汇、控件、表示和服务文档。统一JSON语法只解决解析的一部分,不能替代动作语义和业务数据来源。
调用路径中的每个状态都应可辨认。客户端验证协议、结构和值,服务明确健康、错误、偏好和生命周期;202仅说明受理,进度资源说明执行,业务结果还需最终资源证据。把这些内容混在一个“成功”布尔值里,会使恢复者无法判断究竟发生了什么。
幂等、并发和撤销解决不同问题。稳定标识与替换值避免重放累加,ETag条件写阻止旧快照覆盖新修改,撤销则需要历史、权限和实际副作用范围。HTTP方法名不能代替上述实现,代理或共享文档也不会自动建立跨服务原子性。
容忍演进不等于不验证。未知字段可以不参与本地计算却仍需往返保留;新动作可以出现却不能强迫旧客户端提供新必填语义;内部字段和存储可变化,外部承诺仍需兼容。把边界写清楚比泛称“松耦合”更有操作意义。
配方的采用本身也是设计。按协作范围和当前收益确定先后,先做独立、可验证的小改动;共享数据库、旧接口和组织约束会限制可直接使用的方案。HyperCLI提供一个具体工具视角,但工具支持列表和示例站点属于该版时点,不替代成熟实现与现实环境的核验。
发散与实践
实践筛选选出两条路径:先用Spring HATEOAS固定2.5.0提交实际阅读链接发现、表示装配和HAL-FORMS模板链路,交付六行源码映射与两层计划;再把第8章的小步采用原则用于本批导入状态分离,交付初始决策表和下一次写入的观察计划。
第一项位于ideas/idea-001-深读链接发现与表单能力.md;第二项位于ideas/idea-002-为本批导入选择最小改动.md。已完成公开源码首轮阅读、固定版本核验与初始材料整理,未执行项目测试、HTTP实验、完整深读或新的应用改造。