一.背景

描述技术需求的背景，快速了解方案的上下文。

ex：

聊聊写这个规范文档的背景，在做评审技术方案的时候，发现团队每个人的文档格式不一，千人千面。那如果大家能把一个技术方案描述清楚、能落地，文档就是一种形式，怎么写都行，但是在实践的过程中，还是发现有些技术方案关键点存在遗漏，评审过程中还是需要大家绞尽脑汁去 check，以免按照结论方案去落地，输出的不是一个成熟的产品，甚至 MVP，或者在实施过程中发现有些跨部门协作环节对不上，结果纸上谈兵，根本落不了地。

机制规范永远比人可靠，依赖人不如制定一个规范，帮助我们在输出技术方案的时候，尽量做到 MECE，把相关的人和问题都罗列清楚，紧扣业务，从问题出发，找出关键路径能够落地。

现在基础平台的组件维护成本居高，复杂度仍持续攀升，未来行业各个领域中间件是往标准化方向演进，像 k8s 这样事实标准，后续我们也要往标准化这个方向走，过多的定制方案会绑架公司，脱离行业标准新人上手成本高，aws 的 Well-Architected 的 6 大支柱定义是安全，可靠，高效，低成本，卓越运营，可持续。我们鼓励多造核心发动机，少造轮子，如果具备技术价值，商业价值，成本（效率）价值之一的就是核心发动机，整车，或者悬架，原则上没有商业价值的不做， 外部已经成熟标准化的不做，比较重的相关服务不做。

规范不是死的，初衷还是推动方案落地，格式可以根据方案的实际情况调整，我们会持续迭代优化这个规范原则，大家都在原则下去协同合作，价值共创，发展成一个顾问型、解决方案型、平台型的服务团队。

二.用户故事

用户故事格式规范：

用户故事在软件开发过程中被作为描述用户需求的一种表达形式。为了规范用户故事的表达，便于沟通，权衡做这件事情产生的收益，用户故事通常的表达格式为：作为一个<用户角色>, 我想要<完成活动>, 以便于<实现价值>。

一个完整的用户故事包含三个要素：

1. 角色（who）：谁要使用这个

2. 活动（what）：要完成什么活动

3. 价值（value）：为什么要这么做，这么做能带来什么价值

遵循 INVEST 原则：Idependent（独立的）；Negotiable（可协商的）；Valuable（有价值的）；Estimatable（可评估）；Small（小的）；Testable（可测试的）。

收益需要数据量化，客观，准确，可衡量。例如做这件事之前，用户效率是 xx%，完成之后效率提升 xx%。

二.关键目标

这里列举三个关键目标分类

业务目标：

• 列举产品需要实现的能力矩阵，例如监控实现错误全采样、MQ 实现延迟队列、etc…

收益目标：

• 描述产品对业务和基础平台的收益目标，如：监控存储成本较此前节省 20%、业务研发效率提升 20%。

SLO 目标：

• 列出系统稳定性的关键指标，并且与用户体验有直接关联的，Google sre 工程方法论中总结的 VALET(不需要严格按照这个模式输出，根据具体产品情况，用户体验罗列重点)：

Volume (traffic)

• How much business volume can my service handle?

Availability

• Is the service up when I need it?

Latency

• Does the service respond fast when I use it?

Errors

• Does the service throw an error when I use it?

Tickets

• Does the service require manual intervention to complete my request?

• 容量（流量）

ex:

skywalking aop 支撑多少个探针同时上报

网关 TPS 达到 100k

• 可用性

ex:

MTBF xx

MTTR xx

overall xx%

• 延迟

ex:p99 800ms

• 错误

ex:

mq 丢失 0.01%

错误 trace 丢失 0.01%

• 故障单

ex：人工修复数据单 x 个

三.技术方案

在做技术方案过程中，经常会看到为了一小撮业务需求，或者觉得这样实现简单，那样很麻烦，而去做一些很 ugly 的架构妥协，非常理解大家觉得这样做短期简单、可落地的心情，我们更希望看到的是每个人在各自的领域，都有一套成熟的、高质量、高标准的行业解决方案，无论是站在公司部门角度，还是站在个人职业生涯发展角度，都要长远考虑，不要为了短期结果而牺牲长期价值。技术 leader 应该对自己有极其严酷的高标准，才能促使团队提供高品质的产品。

基础架构要源于业务，高于业务，先于业务，业务发展变化非常快，今天刚好满足需求，明天大概率就是恰好不满足用户需求，基础服务组件要以产品的标准去做要求，而不是做项目的思维，多和三方标准服务共创，少埋头造轮子。

选型对比

列举业界是标准成熟方案，社区活跃，用户基数大，有 roadmap、release plan。

方案一：xxx

• XX 是什么：一句话描述解决什么问题

• 功能特性：feature 能力矩阵

• 实现原理：架构原理，POC 流程（引入独立组件需要有 POC 流程）

方案二：xxx

方案对比（回溯目标，明确我们要解决什么问题，列出跟目标相关的关键的对比项）

ex：

最终方案

这里需要描述清楚为什么要这么设计，决策逻辑是什么，可以从但不限于以下几个关键点切入。

• 动机

• 面临哪些挑战

• 关键决策点

具体技术实施方案，针对不同问题，需要描述的重点也不一样，根据具体项目实际情况调整，此规范只描述通用的关键几项，有缺失的可以完善补充。目的是为了在实施技术方案的过程中，依赖规范机制，帮助大家去 review 技术方案的完整性，以免做出的产品遗漏关键因素，最后输出半成品，造成资源浪费，甚至业务和基础技术部门的信任危机。

架构设计图

清晰的架构图分两部分，一部分是组件，是图上的点，另外一部分是图上的线，体现出点之间的逻辑关系、数据流。

国内阿里腾讯大厂内部很多架构图都喜欢用大图，堆砌能力，没有体现出组件之间的逻辑关系，很难传递有效信息，业内私下称这种架构图叫跑马圈地图，运营对外 PR、marketing 可以，在技术评审场景不适合，下图腾讯云官方的容器服务架构图是典型的反面示例。

!https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/5yBRq1EmPNr5qdv1/img/cf809a31-3420-4715-8f56-c0f7a9e25e74.png

架构图应该简单明了，传递有效信息，例如 moa mesh 架构图。

!https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/5yBRq1EmPNr5qdv1/img/5ae37d1f-a2d2-41a8-8244-5c1b7c8da179.png

描述整体架构设计思路，下面根据设计的关键要点，拆开去讲每个点的设计原理和实施过程。根据具体方案情况调整，主要考虑但不限于以下几个关键点。

1.API 接口设计

Amazon 在 06 年就提出如下理念：

1. API 至上

2. 分布式系统要拥抱 failure

3. 两个披萨团队反应最快

4. 基础设施团队人员不应该和机器数量成正比关系

API 接口是不同系统之间进行通信和集成的关键点，良好设计的 API 接口可以确保系统之间的数据和功能的交互高效可靠，API 接口设计考虑可扩展性，使系统能够方便地添加新的 Feature。通过定义清晰的接口和协议，能力摸标准化、模块化，新功能可以被快速地集成到系统中，而不会对现有的系统造成过多的影响。

如果涉及 API 接口，请按照规范描述接口设计方案。

命名规范格式：Group（API 组）、Version（API 版本）和 Resource（API 资源类)

ex:

/auth/v1/createUser

• 请求参数定义

• 返回报文格式定义

• 回执状态码定义

ex：

• 4xx client error

• 5xx server error

• 200 sucess

2.数据结构/传输协议设计

如果涉及数据结构\传输协议，请按照规范描述设计方案。

互联网的本质是数据的传输，数据处理逻辑是软件设计的核心：数据存储结构设计、数据传输协议设计。

ex:

apiVersion: com.tencent.tsf/v1alpha1  kind: CircuitBreakerRule  metadata:    name: ${RuleName}    servicename: ${Service Name} # 考虑采用被 Micro Service 关联还是Label Select    namespace: ${Namespace}  spec:    rules: # 熔断规则，可以多条，每个服务可以配置多条下游服务的熔断规则    - targetService: #熔断的目标服务    targetServiceName: ${Service Name} #下游熔断的服务名    targetNamespace: ${Namespace} #下游熔断的服务所属命名空间      isolationLevel: ${SERVICE INSTANCE API} #熔断级别    enable: ${true false} #是否生效    - strategy: #只有在API级别熔断的时候，才有多条    - api: #只有是api级别的时候才有，接口列表      path: ${value} # 接口名，一般是 String      method: ${POST,GET} #接口方法    failureRateThreshold: ${value} #请求失败比例达到阈值触发熔断    maxEjectionPercent: ${value} #最大熔断比例，只有在实例级别熔断时候才有    minimumNumberOfCalls: ${value} #最少请求次数    slidingWindowSize: ${value} #滑动窗口时间    slowCallDurationThreshold: ${value} #慢请求时间阈值    slowCallRateThreshold: ${value} #慢请求熔断比例阈值    waitDurationInOpenState: ${value} #启动半开状态的时间间隔

3.可靠性设计

根据具体方案需要，设计技术方案的可靠性，主要考虑但不限于以下几个关键点。

异常保障机制

• ex:异常失败策略，混沌测试，故障演练、断网

高可用方案

ex:集群部署、自动故障恢复、计算存储分离、有状态节点数据一致性，client 负载均衡、server 负载均衡

敬畏生产，灰度上线方案

ex:蓝绿灰度、金丝雀灰度

升级策略

兼容策略

etc

4.可维护性设计

代码设计不仅仅要内聚，项目要尽量标准化、模块化，如果改动项目的一段代码，影响整个项目的逻辑，特别是多人团队协作的项目，意味着开发者改动了任何一个地方，都要考虑所有人所有的功能，这无形中提高了项目协作的门槛。如果经过精良的设计，项目高度模块化之后，改动某个 feature 或者新增 feature 的时候，不会影响到其他功能。

建立一套代码模块化规范、自动化检查和自动化测试机制，保障不会有任何意外的代码合并到主干，如果单靠人肉 review 是很难做到的，人脑能压几个栈，机制永远比人可靠。

• 项目代码模块化、插件化

• ex:能力抽象成标准 API 组件接口，方便扩展，使用 SPI 提供能力插件。

• 机制永远比人可靠

• ex：checkstyle 插件 + 单元测试 + gitlab-ci.yml

5.监控告警方案

所有的基础组件必须有完善的监控告警机制，要在评审文档中有所体现。

6.安全合规设计

安全永远是第一位

可参考 AWS 安全设计原则

• 健壮的身份验证体系：实施最小权限原则，并通过对每一次与 AWS 资源之间的交互进行适当授权来强制执行职责分离。集中进行身份管理，并努力消除对长期静态凭证的依赖。

• 实现可追溯性：实时监控和审计对环境执行的操作和更改并发送警报。为系统集成日志和指标收集功能，以自动调查并采取措施。

• 在所有层面应用安全措施：利用多种安全控制措施实现深度防御。应用到所有层面（例如网络边缘、VPC、负载均衡、每个实例和计算服务、操作系统、应用程序和代码）。

• 自动实施安全最佳实践：借助基于软件的自动化安全机制，您能够以更为快速且更具成本效益的方式实现安全扩展。创建安全架构，包括实施可在版本控制模板中以代码形式定义和管理的控制措施。

• 保护动态数据和静态数据：将您的数据按敏感程度进行分类，并采用加密、令牌和访问控制等机制（如适用）。

• 限制对数据的访问：使用相关机制和工具来减少和消除直接访问或人工处理数据的需求。这样可以降低处理敏感数据时数据处理不当、被修改以及人为错误的风险。

• 做好应对安全性事件的准备：制定符合您组织要求的事件管理和调查策略和流程，做好应对事件的准备工作。开展事件响应模拟演练并使用具有自动化功能的工具来提高检测、调查和恢复的速度。

四.性能测试

如果方案涉及性能测试提供用户关注的性能指标压测数据和结论。

• 压测方案

• 测试环境

• 压测数据

• 测试结论

五.用户接入

描述业务接入方式和成本，职能支撑部门提供的基础组件应该尽量减少业务方介入成本，宁愿我们多走 99 步，也要让业务方少走一步，以业务为中心、构建安全、可靠、高效、低成本、可持续发展的标准化服务。

此处是方案评审的接入描述，和正式的用户接入文档细节上有些不同，评审文档的用户接入部分描述清楚接入方式和成本就可，不需要达到用户 POC 的详细程度，方便评估方案落地的可行性。

ex:

agent 接入流程：

1.添加 appkey

2.服务部署时，部署最新 agent 包

3.启动时添加-javaagent 命令

4.查看监控数据

六.资源协调

技术方案涉及到相关组织、部门资源，技术规划少不了合作方的支持，在评审之前一定要知会到相关方，如果技术方案没有跟相关人员沟通达成一致，大概率是纸上谈兵，落不了地。

七.里程碑计划