ServiceStack API版本化实践方案咨询与技术问题求解

我们团队正为ServiceStack API寻求便捷的版本化实现方案，已查阅相关技术文档但未找到适配本系统的实践路径。

我们梳理了API生命周期中的变更类型：

• 非破坏性变更：新增服务、请求/响应DTO新增属性、为无响应请求DTO添加响应
• 破坏性变更：移除服务、请求/响应DTO移除属性、修改HTTP动词、服务语义变更
• 组合破坏性变更：重命名服务/属性、拆分请求/响应DTO属性

我们的版本命名规则为年度双发版（如2020.1.0）+服务包（如2020.1.1），内部客户端与服务器同步更新无问题，但需为使用API的合作伙伴/客户提供变更缓冲期。我们设想通过客户端指定版本号（Header/URL/查询参数），让ServiceStack仅暴露对应版本的API，参考aspnet-api-versioning的版本标记策略，并进行了初步实验，但存在以下疑问：

1. 能否让ServiceStack仅展示指定版本的兼容服务（如/api?v=20231仅显示2023.1版本服务）？
2. 是否有更适配本系统的版本化方案？能否实现类似aspnet-api-versioning的机制？
3. 是否需将原有未版本化的请求/响应DTO（如GetProjects、Project）重命名为带版本后缀的形式（如GetProjectsV20201），以便ServiceStack识别版本归属？
4. 当发布2023.2版本且GetProjectsV20231无破坏性变更时，如何配置ServiceStack自动使用该最新兼容版本？

实验代码示例 #

// ServiceStack configuration in AppHost
public override void Configure(Funq.Container container)
{
    SetConfig(new HostConfig
    {
        ApiVersion = "20231"
    });

    var nativeTypes = GetPlugin<NativeTypesFeature>();
    nativeTypes.MetadataTypesConfig.AddImplicitVersion = 20231;
}

public class Project
{
    public int ID { get; set; }
    public Guid GlobalID { get; set; }
    public string Number { get; set; }
    public string Name { get; set; }
    public string Description1 { get; set; }
    public string Description2 { get; set; }
    public string City { get; set; }
    public bool Active { get; set; }
}

[Route("/projects", "GET POST")]
public class GetProjects : IReturn<List<Project>>
{
    public string SearchCriteria { get; set; }
    public int PageSize { get; set; } = Constants.DefaultPageSize;
    public int PageNumber { get; set; } = Constants.DefaultPageNumber;
    public string OrderBy { get; set; }
}


public class ProjectV20231
{
    public int ID { get; set; }
    public Guid GlobalID { get; set; }
    public string Number { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
    public string City { get; set; }
    public bool Active { get; set; }
}

public enum OrderByDirection { Asc, Desc }
public class OrderByElement
{
    public string Field { get; set; }
    public OrderByDirection Direction { get; set; }
}

[Route("/projects", "GET")]
public class GetProjectsV20231 : IReturn<List<ProjectV20231>>
{
    public string SearchTerm { get; set; }
    public int Offset { get; set; }
    public int Limit { get; set; }
    public List<OrderByElement> OrderBy { get; set; }
    public bool? Active { get; set; } = null;
}

public class ProjectsService : Service
{
    public List<Project> Get(GetProjects request)
    {
        var result = new List<Project>
        {
            new Project() { Name = "2020.1" }
        };
        return result;
    }

    public List<ProjectV20231> Get(GetProjectsV20231 request)
    {
        var result = new List<ProjectV20231>
        {
            new ProjectV20231() { Name = "2023.1" }
        };
        return result;
    }
}

内容的提问来源于stack exchange，提问作者Robin Bouwmeester