今天聊聊开放平台架构设计。

为什么需要搭建开放平台

增强产品能力

开放平台能够让三方开发者和合作伙伴开发新的应用或服务，增加原有 SaaS 产品能力。这样就可以满足更多用户需求，从而提高用户的满意度和黏性。

促进创新

三方开发者能够在 SaaS 标准产品的基础上，创造新的解决方案，为平台带来创新的业务模式，这些可能为 SaaS 企业带来更多的盈利机会。

构建生态系统

开放平台能够建立一个以 SaaS 标准产品为中心的生态系统，吸引开发者、合作伙伴和其他相关方参加，共同构建一个互惠互利的生态圈。

降低开发和运营成本

通过邀请三方开发者来创造和扩展产品能力，他们可以有效分担 SaaS 企业的开发、运营成本，更聚焦于核心产品的优化和创新。

开放平台的服务对象是谁？

SaaS 企业的开放平台通常包括以下关键用户角色：

第三方开发者

他们期望能快速入驻开放平台，并构建应用，通过用户订购应用获取收益。因此，他们需要 API 文档、SDK 工具和开发者后台，帮助开发者构建、测试和部署应用，并且利用平台资源推广自己的应用。

定制客户

定制客户一般为拥有自研能力的企业客户，有定制化功能需求，例如与内部系统（如 ERP、CRM）进行打通，实现企业自身的业务流程。

平台运营人员

平台运营人员需要为三方开放者和企业客户服务，帮助他们解决问题，因此，需要客户管理，应用申请流程管理、服务配置、参数配置、角色分配、财务对账管理等产品能力。

开放平台的运营流程

SaaS 开放平台的运营流程涉及平台的管理和维护，为企业客户、三方开发者提供服务，包括吸引与管理三方开发者，提供必要的开发工具和支持，对开发者创建的应用进行审核和上线管理，通过数据监控和分析评估平台的健康度和用户活跃度，确保提供有效的服务支持，和维护平台的安全和合规性。

下图展示了开放平台的整体运营流程，实际的开放平台项目可以基于该流程做变更。

开放平台整体架构设计

管理后台

层针对不同角色，提供不同的管理后台：

• 开发者后台：为三方开发者提供的工作台，包括应用管理、API 接入、开发工具、数据分析和测试工具等。

• 平台运营后台：用于平台运营团队管理整个系统的工作台，包括客户管理、权限控制、计费管理、系统监控等功能。

• 商家后台：SaaS 企业客户的后台系统，主要用于订购应用市场的三方应用，授权应用，并使用其提供的服务能力。

服务层

服务层为上层的管理后台提供核心服务能力：

• 开发者接入：提供 API 文档、SDK 工具、开发指南，应用的注册、管理等。

• 运营管理：包括平台用户信息管理、权限设置、用户资料管理。对开发者提交的应用进行审核，确保应用的质量和安全性。管理平台计费、结算，收集和分析平台的运营数据。

• 监控中心：包括服务器、应用、网络、数据库、安全、中间件和存储监控。这些功能确保开放平台的稳定性、性能和安全，通过实时监控、告警支持技术团队进行有效管理和维护。

API 网关

API 网关是整个开放平台的流量入口，它提供的能力确保了平台操作的安全、稳定和高效管理。

业务开放能力

业务开放能力由各个业务域系统提供，这些开放能力提供了核心业务数据/功能的交互能力。

开放能力设计

开放能力可以分为以下几种类型：

• 前端扩展：开发者可创建个性化的前端 H5/小程序页面，满足企业客户不同场景不同行业的需求。

• API 接口/消息推送：API 接口允许开发者通过定义的接口与平台系统交互，实现数据和功能的集成，例如商品创建接口。消息推送是指平台系统主动通知三方系统，如订单状态变更通知。

• 后端扩展：开发者可以通过扩展点，自由嵌入自定义流程节点，构建个性化的业务逻辑。

• 数据模型扩展：允许将三方系统的数据模型整合到平台系统中，在平台系统中可以查看或处理三方数据。

以商品系统为例，列出不同类型开放能力的使用场景：

• 前端扩展：页面串联、定制商详组件、定制商品详情、定制 B 端管理页面。

• API 接口/消息推送：商品发布接口、同步分店接口、查询商品详情接口、商品价格修改接口、商品修改接口、商品属性接口、商品上下架接口、商品类目接口、商品创建消息、商品变更消息。

• 后端扩展：商品校验类扩展点（例如，商品创建时，校验商品编码是否符合定制需求的规范）、商品的定制信息计算扩展点（例如，通过外部接口计算出商品重量信息）。

• 数据模型扩展：商品模型扩展并存储个性化的字段信息。

开放 API 设计原则

RESTful 风格 API

RESTful API 是一种遵循 REST 原则的 API 设计方式。REST 是一组约束条件和原则，由 Roy Fielding 在 2000 年的博士论文中提出。

RESTful API 的设计依赖于网络协议，主要是 HTTP，并且它使用 HTTP 的原生功能（比如 HTTP 的动词和状态码）来执行操作。以下是 RESTful API 的一些主要特点：

• 面向资源：在 REST 架构中，所有内容都被视为"资源"，每个"资源"都有一个独特的 URI（统一资源标识符）。

• 无状态：RESTful API 不保存状态，这意味着每个请求都应包含执行请求所需的信息。服务器不会保存客户端的任何信息。

• 统一接口：RESTful API 应该有一个统一的接口，客户端和服务器基于接口交互，实现解耦。交互通常通过 HTTP 动词实现，如 GET（获取资源）、POST（创建资源）、PUT（更新资源）、DELETE（删除资源）。

RESTful API 的三个显著优势如下：

• 它建立在 HTTP 协议上，协议简洁易用，得到了广泛的应用。

• 接口设计以资源为中心，让接口易于理解和使用，比较直观。

• 数据交换采用 XML 或 JSON 格式，大大简化了数据的处理和传输过程。

但严格遵循 RESTful API 风格，也有一些缺陷：

HTTP 协议的动词受限

当业务需求变得复杂时，仅依赖于 HTTP 的动词方法来对资源操作，可能不足以满足需求，这时往往需要通过接口名称来进一步区分。此外，一些特定的 HTTP 请求，如 PUT 和 DELETE，可能会在网络传输过程中被某些防火墙设备拦截。

URL 包含参数，可读性差

在 URL 中嵌入参数占位符（例如：GET /Api/Orders/{id}/OrderItems/{id}）会降低其可读性。如果需要基于 URL 统计接口的调用次数，需要对具有相同 URL 的不同参数进行额外的处理。

HTTP 状态码的表达性差

使用如 20X、30X、4XX、5XX 等标准的 HTTP 状态码，不足以描述复杂的业务场景的状态。

建议接口设计遵循以下准则：

• 限制 HTTP 方法的使用，仅采用 GET 和 POST。

• 避免在 URL 中包含参数占位符，尽量使用 URL 的参数传参。

• 使用自定义的业务状态码来提供更丰富的响应信息。

API 分组原则

根据业务领域，对开放 API 进行分组。例如店铺 API、商品 API、库存 API、订单 API、物流 API、客户 API、营销 API。

SaaS 标准产品一般都基于 DDD 进行架构设计，根据业务领域组织开放 API，是普遍采用的最佳实践。当需要改进或变更某个特定业务领域的功能时，开发人员可以直接找到相关的 API 组进行修改，不会影响到其他领域的 API。

对于三方开发人员，可以更容易地找到与某个业务功能相关的 API，因为它们通过业务域的划分逻辑组织在一起。

版本管理

为了统一和清晰地标识不同版本的相同接口，建议将版本号放置在接口路径的末尾，示例如下：

• 老版本：http://api.xxxx.com/item/create_item
  

• 新版本：http://api.xxxx.com/item/create_item/v2
  

返回数据

每个接口的响应数据，应遵循统一的 JSON 或 XML 格式规范，并且至少应包含以下关键字段：

• 状态码 (code)：表示请求的总体结果，通常用于标识操作的成功或异常状态。

• 消息 (msg)：提供关于状态码的详细描述，以帮助理解请求的具体结果。

• 数据 (data)：包含与请求相关的具体业务信息和数据。

{	"code":200,	"msg":"OK",	"data":{	"item_id":"123456",	"product_name":"奶油蛋糕"	}}

安全措施

接口签名

为开发者分配 AccessKey（开发者标识，确保唯一）和 SecretKey（用于接口加密，确保不易被穷举，生成算法不易被猜测）。

按照请求参数名的字母升序排列非空请求参数（包含 AccessKey），使用 URL 键值对的格式（即 key1=value1&key2=value2…）拼接成字符串 A。

在字符串 A 最后拼接上 Secretkey 得到字符串 B。

对字符串 B 进行 MD5 运算，得到 Sign 值。请求时，携带参数 AccessKey 和 Sign，只有拥有合法的身份 AccessKey 和正确的签名 Sign 才能放行。这样就解决了身份验证和参数篡改问题，即使请求参数被劫持，由于获取不到 SecretKey（仅作本地加密使用，不参与网络传输），也无法伪造合法的请求。

数据加密

敏感数据，如用户信息，应使用加密算法进行保护，常用的加密方法包括 RSA 和 AES。

访问控制

在接口访问的 API 网关，应设置访问控制，仅允许来自被商家授权的白名单的请求。商家可以通过商家后台系统自主管理其白名单。

消息推送

消息推送是平台主动通知三方系统，提供数据更新的一种机制，满足三方系统对信息实时性的需求。例如，当商家成功创建订单后，三方系统可以通过订单查询接口来获取订单的当前状态。

三方系统若想实时获取订单状态，可以选择定时查询接口，但这样效率低并消耗大量资源。通过系统主动推送订单状态信息，可以有效地解决这一问题。但消息推送也带来了一些挑战：

• 顺序性问题：订单可能经历多个状态，且这些状态在业务上有特定顺序。网络延迟可能导致状态送达三方系统时，顺序错乱，这时三方系统需要通过校验订单状态，判断变更是否符合业务逻辑，来确保订单状态的准确性。

• 消息丢失风险：目前系统通常采用消息队列异步发送消息推送，尽管有消息中间件的机制确保消息的可靠性，但三方系统出现网络问题，仍有可能导致推送失败。解决方案：三方系统可以定期全量查询订单状态，对双边的订单状态进行对账处理，确保数据的完整性。

文章转载自：架构师汤师爷

原文链接：https://www.cnblogs.com/tangshiye/p/18460498

体验地址：http://www.jnpfsoft.com/?from=infoq