构建可直接配合官方 SDK 和 CLI 使用的本地云服务模拟器

## 优先让请求和响应格式与真实云服务一致，而不是图省事 按以下顺序确定优先级： 1. 与上游云协议兼容； 2. 符合官方SDK和CLI客户端预期的行为； 3. 复用现有模拟器的模式； 4. 正确性优先于便利性； 5. 采用范围小且可测试的变更。 不要为了方便实现而添加自定义端点结构，也不要简化请求和响应格式。除非所要求的行为必须依赖广泛重构，否则不要进行此类重构。 编辑前，确定目标服务、控制平面或数据平面角色、协议族、可供仿照的现有实现、对配置的影响、对存储的影响、对文档的影响，以及最小但有效的测试计划。 行为不明确时，依次以如下内容为准：上游平台契约、既有模拟器行为、兼容性测试套件的预期。如果任务需要跨服务的架构变更，应说明取舍，而不是盲目重构。 ## 让协议处理部分保持精简，把业务逻辑放在服务层 采用分层的服务设计： - 控制器或处理程序解析协议输入，并生成与协议兼容的响应； - 服务承载业务逻辑，并抛出共享的云领域异常； - 模型表示领域数据； - 注册表、配置、存储工厂、生命周期服务、解析器、构建器和异常映射器提供共享基础设施。 保持控制器精简。引入新模式前，应复用共享工具，并以结构最接近的既有服务为范本。 通过共享异常类型传递领域故障。查询与XML流程应使用标准异常映射器；JSON协议流程应返回规定的结构化错误正文。控制器返回类型必须继续满足预先编译时反射和序列化的约束。 使用构造函数注入，为条件语句加上大括号，并使代码含义不言自明。绝不要留下空的catch块；如果有意容忍某个异常，应记录足够的上下文以便诊断。 ## 添加操作前，先确认该服务真实使用的协议 添加操作前，先确定实际使用的线级协议： - 查询协议使用表单编码的操作和XML响应； - JSON RPC风格的协议使用目标请求头和结构化JSON； - REST JSON和REST XML使用资源路径及各自的原生正文格式； - 数据平面服务可能需要原生TCP代理，而不是HTTP管理API。 使用共享的XML构建器、解析器和命名空间常量。绝不要用正则表达式解析XML。JSON错误应与目标协议的错误结构保持一致。 有些服务会提供不止一条兼容路径。保持各备用处理程序一致，并一同测试。应按身份发现端点实际采用的开放协议处理它们，不要强行套用管理API模型。 应通过官方SDK客户端验证管理API，而不能只依赖手工构造的HTTP请求。某个手工载荷能被接受，并不能证明客户端序列化、请求头、错误、分页或URL生成具备兼容性。 ## 始终同时修改存储方式和配置文件 通过共享工厂和已声明的模式支持存储；绝不要在服务内部直接实例化某种存储实现。遵循用于加载、刷写、检查点或预写行为的生命周期钩子。 当接口默认值与部署值不同时，将仓库中的运行时配置文件视为有效的事实来源。 对于与存储有关的行为： 1. 更新规范配置接口； 2. 更新主要运行时配置； 3. 更新测试配置； 4. 通过存储工厂接入该模式； 5. 验证生命周期集成。 对于任何面向用户的配置，还要更新文档并遵循既有的环境变量命名约定。如果基础URL、主机名、区域和账户默认值、端口范围、持久化根目录或容器网络会影响所生成的标识符或端点，也要审查这些内容。 以兼容方式添加新字段，并使共享配置、存储和服务注册保持同步。 ## 用官方 SDK 而不是手工请求来测试兼容性 使用单元测试验证隔离的服务行为，使用集成测试验证协议处理、持久化和客户端可见状态。只有当行为有意设计为有状态时，才可以按顺序执行集成测试。 凡是对解析、响应结构、错误、持久化语义、URL生成、服务启用方式或备用协议路径的变更，都必须有自动化测试覆盖。 迭代期间先运行聚焦测试，再运行直接相关的测试套件。如果变更可能影响真实SDK行为，应使用兼容性项目。优先使用基于SDK的断言，而不是原始HTTP请求，并记录任何有意偏离上游行为之处。 当备用协议路径公开同一操作时，应测试其语义是否等价。当状态会持久化时，应在相关存储模式下验证加载和刷写行为。 不要仅凭手工请求就声称实现了兼容性。如果行为发生变化却没有自动化测试覆盖，应说明缺少哪项测试，以及无法添加它的原因。 ## 完整做完新服务，不顺手改动发布流程 添加服务时，应创建其控制器、服务和模型；完成注册；添加规范配置和测试配置；通过工厂连接存储；添加测试；并更新文档。 完成前： - 运行相关测试和协议兼容性检查； - 确认未引入自定义端点或为求便利而设计的线级格式； - 验证配置、存储、生命周期和文档更新； - 检查所生成的URL和资源标识符是否一致； - 在热点路径中保持日志结构化且安静。 保持拉取请求范围集中；除非明确要求变更，否则应保留现有行为；并将无关重构分离。使用约定式提交类型，并仅标注人类作者。 将发布分支、标签和发布工作流视为关键基础设施。合并到开发分支本身并不能证明发布版本稳定。在实现服务功能时，不要顺带更改发布行为。