devex-sdk-design

开发者体验与 SDK 设计

SDK 设计原则

API 易用性

// Bad: too many required params, unclear ordering
createUser(name, email, role, true, false, null, 'active');

// Good: builder pattern with named properties
const user = await sdk.users.create({
  name: 'Alice',
  email: '[email protected]',
  role: 'admin',
});

// Good: fluent API for complex operations
const results = await sdk.query('users')
  .where('role', '=', 'admin')
  .orderBy('createdAt', 'desc')
  .limit(10)
  .execute();

渐进式披露

// Simple case: just works with defaults
const client = new MySDK('api-key');
const result = await client.doThing();

// Advanced case: full control available
const client = new MySDK({
  apiKey: 'api-key',
  baseUrl: 'https://custom.endpoint.com',
  timeout: 30000,
  retries: { maxAttempts: 3, backoff: 'exponential' },
  middleware: [loggingMiddleware, authRefreshMiddleware],
});

错误设计

// SDK errors should be structured and actionable
class SDKError extends Error {
  constructor(
    message: string,
    public readonly code: string,        // machine-readable
    public readonly statusCode?: number,  // HTTP status if applicable
    public readonly retryable: boolean = false,
    public readonly docs?: string,        // link to relevant docs
  ) {
    super(message);
  }
}

// User sees:
// SDKError: Rate limit exceeded (rate_limit_exceeded)
//   Retryable: true, retry after 2.3s
//   Docs: https://docs.example.com/rate-limits

CLI 设计

命令结构

mycli <command> <subcommand> [flags]

mycli init                    # Interactive setup
mycli deploy --env production # Explicit flags
mycli logs --follow           # Streaming output
mycli config set key value    # Noun-verb pattern

CLI 最佳实践

• 合理的默认值： 开箱即用，通过 --flag 自定义
• 渐进式输出： 长时间操作显示旋转指示器，使用 --verbose 调试，使用 --json 供机器读取
• 确认提示： 破坏性操作需要 --yes 或交互式确认
• Shell 补全： 为 bash/zsh/fish/PowerShell 生成补全
• 退出代码： 0 = 成功，1 = 错误，2 = 用法错误

文档驱动开发

README 结构（适用于 SDK）

1. 一句话介绍： 用一句话说明它的作用
2. 快速入门： 可复制粘贴的可运行示例（< 10 行）
3. 安装： 包管理器命令
4. 用法： 常见模式及代码示例
5. API 参考： 根据类型/文档字符串自动生成
6. 错误处理： 常见错误及解决方案
7. 迁移指南： 不同版本之间的破坏性变更

代码示例

• 每个公共方法都需要用法示例
• 示例必须能够编译/运行，并在 CI 中测试
• 先展示正常流程，再展示边界情况
• 在注释中包含预期输出

开发者入门指标

• Hello World 所需时间： 从阅读文档到运行代码少于 5 分钟
• 首次 API 调用所需时间： 包含身份验证设置在内少于 10 分钟
• 复制粘贴成功率： 快速入门示例首次运行即成功
• 错误解决时间： 错误消息能直接引导用户修复问题

版本控制与破坏性变更

• 严格遵循语义化版本
• 移除前提前 2 个次要版本发出弃用警告
• 为主要版本升级提供迁移 codemod
• 每次发布都附带变更日志（keep-a-changelog 格式）