Azure SDK for .NET 库清单生成与分类指南

Azure SDK for .NET 库清单生成与分类指南

azure-sdk-for-net 此代码库用于积极开发Azure SDK for .NET。对于SDK的用户，我们推荐访问我们的公共开发者文档 https://learn.microsoft.com/dotnet/azure/ 或我们版本化的开发者文档 https://azure.github.io/azure-sdk-for-net。 项目地址: https://gitcode.com/gh_mirrors/az/azure-sdk-for-net

前言

在大型软件开发项目中，特别是像Azure SDK for .NET这样包含数百个库的项目，维护一个清晰的库清单至关重要。本文将详细介绍如何生成和管理Azure SDK for .NET中的库清单，帮助开发者理解项目结构并规划未来的技术迁移。

库清单的重要性

库清单不仅仅是一个简单的列表，它为项目维护者提供了以下关键信息：

1. 全局视图：展示项目中所有库的完整清单
2. 分类体系：将库划分为数据平面(Data Plane)和管理平面(Management Plane)
3. 技术栈分析：标识每个库使用的代码生成器(Swagger或TypeSpec)
4. 迁移规划：为从旧生成器(Swagger)迁移到新生成器(TypeSpec)提供依据

生成库清单的步骤

基本生成方法

1. 定位到项目根目录
2. 执行以下命令：

python doc/GeneratorMigration/Library_Inventory.py

3. 脚本执行完成后，会在doc/GeneratorMigration/目录下生成：
   • Library_Inventory.md：人类可读的Markdown格式报告
   • (可选)Library_Inventory.json：机器可读的JSON格式数据(需添加--json参数)

高级选项

如果需要JSON格式输出用于自动化分析，可以添加--json参数：

python doc/GeneratorMigration/Library_Inventory.py --json

注意：JSON文件仅用于临时分析，不应提交到代码仓库中。

分类逻辑详解

平面类型分类

脚本采用以下逻辑区分数据平面和管理平面库：

• 管理平面(Management Plane)：

  • 路径中包含"Azure.ResourceManager"
  • 路径中包含".Management."

• 数据平面(Data Plane)：

  • 不符合上述条件的其他所有库

生成器类型分类

脚本通过以下优先级判断库使用的生成器类型：

TypeSpec(TSP)识别标志

1. 存在tsp-location.yaml文件且包含emitterPackageJsonPath值
2. 存在src/tspconfig.yaml文件
3. 存在src/tsp目录
4. src目录中存在.tsp文件

Swagger识别标志

1. 存在src/autorest.md文件
2. 存在src/Generated目录
3. 文件头部包含<auto-generated/>注释

如果未找到TypeSpec标志但存在代码生成证据，则默认归类为Swagger生成。

解读清单报告

生成的Markdown报告包含以下关键部分：

1. 总体统计：各类库的数量汇总
2. 详细分类表：
   • 使用TypeSpec的数据平面库
   • 使用Swagger的数据平面库
   • 使用TypeSpec的管理平面库
   • 使用Swagger的管理平面库
   • 生成器类型未知的库

最佳实践

1. 定期更新：建议在以下情况下重新生成清单：

   • 新增库时
   • 库从Swagger迁移到TypeSpec后
   • 准备迁移计划前

2. 版本控制：只将Markdown格式的清单纳入版本控制

3. 数据分析：JSON格式可用于：

   • 生成可视化图表
   • 跟踪迁移进度
   • 识别技术债务

技术背景补充

数据平面 vs 管理平面

• 数据平面：直接与Azure服务交互，执行具体业务操作
• 管理平面：管理Azure资源本身，如创建、配置、删除资源

Swagger vs TypeSpec

• Swagger(OpenAPI)：传统的API描述语言，使用YAML/JSON格式
• TypeSpec：微软新一代API描述语言，提供更强大的类型系统和抽象能力

结语

通过维护准确的库清单，Azure SDK for .NET团队能够更好地掌控项目技术栈，规划技术演进路线。本文介绍的工具和方法不仅适用于本项目，也可作为其他大型.NET项目的参考实践。

azure-sdk-for-net 此代码库用于积极开发Azure SDK for .NET。对于SDK的用户，我们推荐访问我们的公共开发者文档 https://learn.microsoft.com/dotnet/azure/ 或我们版本化的开发者文档 https://azure.github.io/azure-sdk-for-net。 项目地址: https://gitcode.com/gh_mirrors/az/azure-sdk-for-net