devex-sdk-design

用途

该技能面向开发者体验（DX）工程，覆盖 SDK 设计模式、API 易用性、CLI 工具设计、文档驱动开发以及开发者上手引导。资料说明其适用于设计 SDK、改进 API 易用性、构建开发者工具或编写开发者文档的场景。

SDK 设计原则

API 易用性

资料以 TypeScript 示例对比了不佳与良好的 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: 'alice@example.com',
  role: 'admin',
});

以及面向复杂操作的流式 API：

// 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 错误应当结构化且可操作，示例代码：

// 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 = 用法错误

文档驱动开发

SDK 的 README 结构

一句话说明： 用一句话描述其功能
快速开始： 可复制粘贴的运行示例（少于 10 行）
安装： 包管理器命令
使用： 常见模式与代码示例
API 参考： 从类型/文档字符串自动生成
错误处理： 常见错误与解决方案
迁移指南： 版本间的破坏性变更

代码示例

每个公开方法都需要使用示例
示例必须可编译/可运行——在 CI 中测试它们
先展示正常路径，再展示边界情况
在注释中包含预期输出

开发者上手指标

Time to Hello World： 从阅读文档到代码可用少于 5 分钟
Time to first API call： 包含认证设置在内少于 10 分钟
复制粘贴成功率： 快速开始示例一次成功
错误解决时间： 错误信息直接指向修复方法

版本管理与破坏性变更

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

限制

资料未提供具体安装命令、收费信息、价格、平台支持情况、效果数据或使用步骤，这些事实暂未提供。