Microsoft API 设计指南：命名规范详解

前言

在API设计中，良好的命名规范是提升开发者体验的关键因素之一。Microsoft API设计指南中的命名规范章节为开发者提供了一套系统化的命名原则，帮助创建一致、直观且易于理解的API接口。本文将深入解析这些规范，并补充实际应用中的注意事项。

命名基本原则

API命名应当遵循"自解释"原则，即开发者无需频繁查阅文档就能理解其含义。这要求我们：

1. 使用完整单词而非缩写（公认的领域专有缩写除外，如Url）
2. 避免使用含义模糊的通用词汇（如Context、Scope等）
3. 保持命名风格的一致性

大小写规范

1. 驼峰式命名：所有标识符（命名空间、实体类型、属性等）必须使用小驼峰式(lowerCamelCase)
   • 示例：userName、accountStatus
2. 首字母缩写处理：应视为普通单词处理大小写
   • 正确示例：url、jsonPayload
   • 错误示例：URL、JSONPayload
3. HTTP头例外：遵循标准HTTP头命名规范（首字母大写的连字符格式）
   • 示例：Content-Type、Authorization

命名避坑指南

以下词汇因在API领域过度使用导致含义模糊，应当避免：

1. Context - 上下文含义过于宽泛
2. Scope - 在不同场景下含义差异大
3. Resource - REST中已有特定含义

复合命名规范

1. 避免冗余冠词：
   • 不佳示例：theAccount、aUser
   • 推荐示例：account、user
2. 类型后缀原则：
   • 当属性名可能引起歧义时，应在末尾添加类型
   • 示例：createdDateTime（而非dateTimeCreated）
3. 外键表示法：
   • 使用关联名称+Id表示外键
   • 示例：subscriptionId

特殊数据类型命名

标识属性

1. 必须使用字符串类型
2. OData服务必须使用@id表示规范标识符
3. 简单场景可使用id表示本地主键

日期时间属性

数据类型	后缀	示例
日期+时间	DateTime	createdDateTime
仅日期	Date	birthDate
仅时间	Time	appointmentStartTime

名称属性

1. 面向用户的资源名称必须使用displayName
2. 其他常见命名属性：
   • givenName（名）
   • surname（姓）
   • signInName（登录名）

集合与计数命名

1. 集合命名：
   • 必须使用正确的英文复数形式
   • 示例：users、documents
   • 非常用复数可使用简化形式（如schemas而非schemata）
2. 计数属性：
   • 必须使用名词+Count后缀
   • 示例：userCount、documentCount

常用属性名对照表

以下是必须遵守的标准属性名（部分）：

属性名	用途说明
displayName	面向用户的显示名称
createdDateTime	创建时间戳
lastModifiedDateTime	最后修改时间
contentUrl	内容URL地址
eTag	实体标记（用于乐观并发控制）
userPrincipalName	用户主体名称
postalCode	邮政编码

最佳实践建议

1. 保持一致性：同一API内相同概念应使用相同命名
2. 领域适配：在特定领域可适当采用该领域的专业术语
3. 可读性优先：宁可名称稍长也要确保含义明确
4. 避免创新：尽量使用行业通用词汇而非自创术语

总结

良好的API命名规范能显著降低开发者的认知负担，提升开发效率。Microsoft的这套命名指南融合了行业最佳实践，既考虑了通用性又兼顾了特定领域的专业需求。在实际API设计中，建议团队内部建立命名评审机制，确保规范得到有效执行。

记住：优秀的API设计应当让开发者"望文生义"，这正是良好命名规范的价值所在。