24 lines
1.3 KiB
Markdown
24 lines
1.3 KiB
Markdown
|
---
|
|||
|
|
name: 接口协议特征描述规范
|
|||
|
|
description: 当接口使用特定通信、网络或接口协议时，必须系统化描述其关键特征以确保双方对协议行为和异常恢复机制有一致理解。在需要编写或审查接口协议文档、设计新协议或排查协议相关问题时使用本技能。
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 接口协议特征描述规范
|
|||
|
|
|
|||
|
|
## 何时使用
|
|||
|
|
- 接口明确依赖某种协议（如 HTTP、TCP、自定义二进制协议等）
|
|||
|
|
- 需要为接口协议编写完整的技术规范文档
|
|||
|
|
- 协议行为存在歧义或需明确异常处理机制
|
|||
|
|
- 不适用于无协议的简单数据传递接口
|
|||
|
|
|
|||
|
|
## 如何执行
|
|||
|
|
对所使用的接口协议，必须完整描述以下六类特征：
|
|||
|
|
|
|||
|
|
1. **唯一标识符**：明确协议名称、版本号及全局唯一标识
|
|||
|
|
2. **协议层次**：说明协议在通信栈中的层级（如应用层、传输层）
|
|||
|
|
3. **打包与路由**：描述数据的打包、拆包、重新打包机制，以及路由和寻址规则
|
|||
|
|
4. **错误控制**：定义合法性检查方法、错误检测机制及恢复流程
|
|||
|
|
5. **同步机制**：说明连接的建立、维护和终止方式（如同步/异步、长连接/短连接）
|
|||
|
|
6. **状态报告**：列出需暴露的状态信息、标识符及其他运行时报告内容
|
|||
|
|
|
|||
|
|
确保描述内容足以让协议双方在正常和异常场景下均能正确交互。
|