API 与 SDK 命名
核心发现：API 命名的核心矛盾是”描述性 vs 简洁性”——RESTful 端点追求资源的准确描述（名词化、复数化），而 SDK/CLI 工具则追求一个短小、有个性、能成为动词的名字。 信息源：restfulapi.net、Moesif Blog、smallstep.com CLI 诗学、各工具官方文档
一、RESTful API 端点命名
核心原则
1. 用名词不用动词——HTTP 方法就是动词
# ❌ 动词冗余
POST /createUser
GET /getUsers
DELETE /removeUser/123
# ✅ 名词 + HTTP 方法
POST /users → 创建用户
GET /users → 获取用户列表
GET /users/123 → 获取特定用户
PUT /users/123 → 更新用户
DELETE /users/123 → 删除用户2. 使用复数名词
# ❌ 单数——暗示只有一个
/user
/order
# ✅ 复数——表示资源集合
/users
/orders
/products3. 小写 + 连字符（kebab-case）
# ❌ 各种不统一
/UserProfiles
/user_profiles
# ✅ 统一格式
/user-profiles
/order-items
/shipping-addresses4. 资源嵌套表达关系，但避免过深
# ✅ 一层嵌套——清晰
GET /users/123/orders → 用户123的所有订单
# ❌ 过深嵌套——难以维护
GET /users/123/orders/456/items/789/reviews
# ✅ 拍平替代
GET /order-items/789/reviews5. 版本号包含在路径中
/v1/users
/v2/users6. 避免文件扩展名
# ❌
/users/123.json
# ✅ 用 Content-Type Header 指定格式
GET /users/123
Accept: application/jsonAPI 命名反模式
| 反模式 | 示例 | 问题 |
|---|---|---|
| 动词端点 | /getAllUsers | 与 HTTP 方法冗余 |
| 缩写 | /usr/123/addr | 可读性差 |
| 大小写混用 | /UserOrders | 不同系统处理不一致 |
| CRUD 拼接 | /deleteUser/123 | 违反 REST 资源模型 |
| 过深嵌套 | /a/1/b/2/c/3/d/4 | 耦合严重，难以演进 |
二、SDK/库的命名
成功的 SDK 命名展现了与 API 命名完全不同的策略——它们追求的是品牌性和记忆度，而非描述性。
经典案例分析
| 库 | 命名策略 | 为什么好 |
|---|---|---|
| requests (Python) | 直接用功能词 | 一看就知道干什么：“发请求”。动词化（import requests）自然流畅 |
| axios (JS) | 造词 | 简短独特、全球可搜索、不与任何已有概念冲突 |
| lodash (JS) | 造词（致敬 underscore.js 的 _） | 独特、简洁、_ 的精神继承但名字更好搜索 |
| Flask (Python) | 隐喻——实验烧瓶 | 暗示”小型、实验性”，与其微框架定位一致 |
| Django (Python) | 致敬人名（Django Reinhardt） | 独特、有文化底蕴、好发音 |
| Express (JS) | 形容词——快速 | 一个词传达了核心价值主张（速度和简洁） |
| NumPy | 缩写组合（Numerical Python） | 领域信号明确，发音清晰 |
SDK 命名策略光谱
描述性 ←——————————————————————→ 品牌性
requests react-router axios Django lodash
│ │ │ │ │
功能词 组合描述 造词 致敬人名 造词+致敬规律：越是通用工具（HTTP 库、Web 框架），越倾向品牌化命名；越是特定领域工具（react-router, webpack-dev-server），越倾向描述性组合。
生态一致性
成功的库会形成命名生态：
axios→axios-cache-plugin,axios-extensions,axios-api-versioningreact→react-router,react-dom,react-nativevue→vue-router,vuex,vue-cli
核心包用品牌名，周边包用 品牌-功能 组合——这是事实上的行业标准。
三、CLI 工具命名
CLI 工具命名是技术命名中最有”诗意”的领域。smallstep.com 的分析称之为”CLI 命令名的诗学”。
CLI 命名原则
1. 短名字留给高频工具
2-5 个字母的短名字是稀缺资源，应该留给每天敲几十次的工具：
cd, ls, cp, mv, rm ← 高频核心命令
git, ssh, vim, curl ← 每日工具
brew, yarn, pip, cargo ← 包管理器2. 打字手感（Ergonomics）
# ❌ 需要 Shift 键的
VirtualBox, easy_install
# ❌ 手指移动距离大的
sha256sum ← "像嚼砂子"
# ✅ 手感流畅的
curl ← 一次手指波动
vim ← 三指快速敲击3. 绝对禁用词
以下词不应出现在任何 CLI 工具名中：tool, kit, util, easy。它们不传达任何信息。
4. 命名空间用子命令，不要污染全局
# ❌ 每个功能一个独立命令
git-add, git-commit, git-push
# ✅ 子命令模式
git add, git commit, git push经典 CLI 工具命名溯源
| 工具 | 命名来源 | 策略类型 |
|---|---|---|
| brew (Homebrew) | “在 Mac 上按你的口味酿造软件”，啤酒主题（Cask, Tap, Formula） | 隐喻体系 |
| cargo (Rust) | 运载货物——配合 Rust 的”crates”（板条箱）概念 | 隐喻一致 |
| pip (Python) | 递归缩写：“pip installs packages” | 递归幽默 |
| yarn (JS) | “Yet Another Resource Negotiator” | 缩写词 |
| curl | ”see URL”的谐音 + 动词”卷取” | 双关 |
| vim | ”Vi IMproved” + “vim”有”活力、精力”之意 | 缩写+双关 |
| grep | 来自 ed 编辑器命令 g/re/p（globally search regular expression and print） | 技术简写 |
| awk | 三位作者姓氏首字母（Aho, Weinberger, Kernighan） | 人名 |
| gcc | GNU Compiler Collection | 描述性缩写 |
隐喻体系案例：Homebrew
Homebrew 构建了一个完整的啤酒酿造隐喻：
| 概念 | 啤酒隐喻 | 实际含义 |
|---|---|---|
| 安装包 | Formula（配方） | 软件包定义 |
| GUI 应用 | Cask（酒桶） | macOS 应用安装 |
| 源仓库 | Tap（龙头） | 第三方软件源 |
| 安装目录 | Cellar（酒窖） | 软件安装路径 |
| 安装操作 | brew install（酿造） | 编译安装 |
这个隐喻体系的成功在于：所有概念都在同一个语义场内，学会了隐喻就能推断出不熟悉的术语含义。
信息源
核心参考
- REST API URI Naming Conventions — restfulapi.net
- The Poetics of CLI Command Names — smallstep.com
- Moesif — The Ultimate Guide to REST API Naming Convention