优化dotnet-docker项目中的Samples标签文档结构

在dotnet-docker项目中，Samples部分的标签文档随着版本迭代变得日益复杂，这给用户选择合适的基础镜像带来了不必要的困扰。本文将介绍如何通过简化标签文档结构来提升用户体验。

背景

dotnet-docker项目为.NET开发者提供了官方支持的Docker镜像，其中包含多个示例应用（Samples）。每个示例应用都有多种变体，对应不同的操作系统版本（如Alpine、Ubuntu）和架构（如amd64）。随着.NET版本的更新，这些标签的数量呈指数级增长。

问题分析

当前文档中，每个示例应用都列出了完整的标签组合，包括：

• 包含架构信息的完整标签（如dotnetapp-9.0-alpine-amd64）
• 不包含架构信息的简化标签（如dotnetapp-9.0）
• 版本别名（如dotnetapp表示8.0版本）
• 最新版本标记（如latest）

这种完整的标签列表虽然信息全面，但对于大多数用户来说过于复杂，特别是当他们只需要了解基本选择时。

解决方案

通过分析用户实际使用场景，我们发现：

1. 大多数用户不需要显式指定架构，Docker会自动选择适合当前环境的镜像
2. 架构特定的标签主要用于高级场景或CI/CD流水线
3. 简化后的标签列表更易于理解和选择

因此，我们决定从文档中移除架构特定的标签，仅保留最常用的简化形式。例如：

• 保留dotnetapp-9.0，移除dotnetapp-9.0-alpine-amd64
• 保留dotnetapp-chiseled-9.0，移除dotnetapp-chiseled-9.0-amd64

实现效果

简化后的文档具有以下优势：

1. 更清晰的视觉层次，减少用户认知负担
2. 聚焦于最常见的使用场景
3. 保留了所有功能可能性（架构特定标签仍然存在，只是不在文档中显式列出）
4. 更易于维护，减少版本更新时的工作量

技术实现

这一改进是通过修改dotnet-docker-tools项目中的文档生成逻辑实现的。主要变更包括：

1. 更新标签生成算法，过滤掉架构特定的标签
2. 确保版本别名和最新标记仍然保留
3. 保持Dockerfile链接的准确性

最佳实践建议

对于使用dotnet-docker示例镜像的用户，我们建议：

1. 优先使用不包含架构信息的简化标签
2. 仅在需要特定架构时才使用完整标签
3. 使用版本别名（如dotnetapp）来获取长期支持版本
4. 谨慎使用latest标签，特别是在生产环境中

总结

通过简化Samples部分的标签文档，我们显著提升了dotnet-docker项目的用户体验。这一改进体现了"约定优于配置"的设计理念，使开发者能够更轻松地开始使用.NET容器化技术，同时保留了高级用户需要的灵活性。