7、API命名：语言、语法与案例启示

API命名：语言、语法与案例启示

1. 语言选择

在软件工程领域，若要选择一种使用最广泛的语言，美式英语目前是首选。这并非意味着美式英语优于或劣于其他语言，而是为了实现全球范围内的最大互操作性。使用美式英语有诸多好处，例如采用英语概念（如用 BookStore 而非 Librería），优先使用常见的美式拼写（如 color 而非 colour），并且大多能适配 ASCII 字符集。

不过，API 注释不一定要用美式英语。若 API 的受众仅在法国，用法语提供文档是合理的。但由于使用该 API 的软件工程师团队可能还会使用其他 API，而这些 API 不太可能仅针对法国客户，所以即便 API 的受众不以美式英语为主要语言，API 本身仍应将美式英语作为各方通用的共享语言。

2. 语法考量

2.1 祈使动作

在 API 中，存在类似编程语言“函数”的部分，负责执行 API 预期的实际工作。对于纯 RESTful API，其依赖预设的标准动作列表（如 Get、Create、Delete 等），动作命名形式为 <标准动词><名词>（如 CreateBook）。而对于非 RESTful 或面向资源的 API 且允许使用非标准动词时，命名选择更多。

REST 标准动词的一个重要共性是使用祈使语气，即命令形式。例如“Create that book!” “Delete that weather reading!”等。但有时函数名会采用陈述语气，如 C# 中的 String.IsNullOrEmpty()，这里的动词“to be”是在询问资源情况，而非下达命令。在 Web API 中使用这种语气会引发一