🧑🏻‍💻 SDK 设计指南

October 15, 2024 (1mo ago)

📏 无规矩，无以成方圆。

这些天一直在忙于工作上业务领域相关的 SDK 设计，在设计过程中期望集思广益，给予一些设计参考。

SDK 的定义

SDK 顾名思义，Software Developer Kit，软件开发者工具包，一般来说应该包含：

  • 支撑软件编程运行时的相关框架（Framework）
  • 内部模块对外开放的编程接口（API）
  • 配套的开发者工具（IDE、Cli 等）

设计原则

为了设计好一套服务于广泛开发者的 SDK，我从一些列文章中摘取了部分重要的设计原则：

「结构清晰」：让 SDK 的使用变得简单

  • 最小核心：API 的数量应该尽可能足够少，少即是多
  • 职责单一：类和模块的功能职责尽量松耦合，不带特定业务逻辑
  • 扩展机制：尽量让非核心的功能通过外部扩展实现和核心模块解耦
  • 命名统一：使用统一的命名规范，认真谨慎地做 API 命名
  • 简单设计：API 的出入参和功能设计尽可能简单，瘦接口设计和原子化的函数方法拆解为之所求
  • 文档配套：关注文档配套尽可能具体详细，提供 API Spec 的同时，也要提供设计和使用相关的 Guide

「稳定高速」：保证 API 的性能和质量是可靠的

  • 测试保障：使用单元测试和 CI 等机制保证 API 的稳定性
  • 关注性能：对于越高频调用的 API 进行性能分析 & 优化
  • 异步接口：关注接口的异步化，在要不阻塞主流程的场景下推荐使用异步调用
  • 善用日志：为 API 提供完整的运行时日志分级，便于开发者调试和研发保障应用稳定性
  • 缩小体积：尽可能降低 SDK 和框架、API 相关包的体积

「向下兼容」：给出兼容策略，保证 API 出炉后有始终如一的觉悟

  • 始终如一：提供版本追溯机制，对外开放 API 命名、出入参、功能保持不变
  • 渐进演化：对于一定要破坏式更新的 API，尽量使用 @deprecated 标识符通知开发者升级兼容，并给出足够多的时间（通常 2-3 个大版本）后再进行移除
  • 发布日志：务必提供完善的 API or SDK 的发布日志

当然，软件工程中，部分重要的设计模式、设计指南也可以提升 SDK 的代码设计质量，比如：

设计目标例子

以 xstate 状态机库设计为例 x-state-design-goals ：

  • Adherence to the W3C SCXML Specification (opens new window)and David Harel's original statecharts formalism
  • Promote an Actor model (opens new window) event-based architecture
  • Compatibility with all frameworks and platforms
  • Ability to completely serialize machine definitions to JSON (and SCXML)
  • Pure, functional createMachine(...) API
  • Zero dependencies

参考


Arno Crafting Apps

ELABORATION STUDIO 🦄

Elaborate your ideas and solve your problems with AI in fully boosted context way ~