介绍

一般准则有利于：

• 特定语言准则作者。

• 没有特定语言准则的语言的客户端库设计者。

如果您使用的语言没有特定的语言准则，请更密切地与 Azure 开发者体验架构委员会合作，以确保客户端库设计得当，开发者体验优异。

设计原则

Azure SDK 的设计应该提高使用 Azure 服务开发者的生产力。 其他质量（例如完整性、可扩展性、性能）虽然重要，但是是次要的。生产力是通过遵循以下原则实现的：

符合语言特性

• SDK 应该遵循目标语言的一般设计准则和语言习惯，它应该让目标语言开发者感到自然。

• 我们拥抱生态系统的优缺点。

• 我们和生态系统一起为所有开发者改进它。

一致性

• 客户端库应该在语言内保持一致，与服务保持一致，并且在所有目标语言间保持一致。在冲突的情况下，在语言内保持一致是最高优先级，在所有目标语言间保持一致是最低优先级。

• 日志记录、HTTP 通信、错误处理等与服务无关的概念应该是保持一致的。开发者在不同客户端间迁移时，不应该要重新学习与服务无关的概念。

• 在客户端库和服务之间的术语一致性有助于诊断。

• 在服务和客户端间的所有不一致必须要有一个好的（清晰的）理由，根源在于习惯用法而不是一时兴起。

• 每一种目标语言的 Azure SDK 感觉像单个团队开发的单个产品。

• 不同目标语言的 SDK 应该有对等功能。这比不同服务间的对等功能更重要。

容易上手

• 我们是支持技术方面的专家，因此我们的客户和开发者不必如此。

• 开发者应该找到优秀的文档（英雄教程、如何写作、示例和 API 文档）让 Azure 服务更容易成功。

• 通过使用实现最佳实践的可预测默认设置，起步应该很简单。想想渐进式的概念披露。

• SDK 应该很容易通过目标语言和生态体系中的最常见的机制获取。

• 开发者在学习新的服务概念时可能会不知所措。核心使用示例应该可被发现。

可诊断

• 开发者应该能够理解正在发生的事情。

• 何时和什么情况下进行网络调用应该是可发现的。

• 默认值是可发现的且意图明确。

• 日志记录、追踪和错误处理是基本的，应该仔细考虑。

• 错误信息应该要明确、和服务相关、可执行和可读。理想情况下，错误信息应该引导消费者做出有用操作。

• 与目标语言的首选调试器继承应该很简单。

可靠

• 破坏性更新比大部分新特性和改进更损害开发者体验。

• 不兼容性绝不应该在没有彻底评审和非常有力的理由的情况下故意引入。

• 不要依赖那些会迫使我们考虑兼容性的依赖项。