C#11及以上版本中如何优雅紧凑定义Response类型专属别名？

适用环境 #

.NET 6（C# 10）、.NET 7（C# 11及更高版本）

场景说明 #

在暴露API接口的场景中，我们希望接口定义严谨，同时不向终端用户暴露底层集合类型。例如以下代码：

public class Item {
    public int x { get; set;}
}

public interface IMyController {
    public Task<IEnumerable<Item>> GetItems();
}

public class MyController {
     public async Task<IEnumerable<Item>> GetItems() {
          return new List<Item>() { /* 初始化数据 */ };
     }
}

我们需要为IEnumerable<Item>定义一个语义化的类型名（如GetItemsResponse），类似TypeScript中GraphQL的实现方式：

export interface Item { ... }
export type Items = Item[];
export type GetItemsResponse = Items;

但C#没有按需全局类型别名机制，现有方案存在诸多不足。

现有方案及不足 #

方案1：文件内局部别名 #

在接口文件中定义局部别名：

using GetItemsResponse = IEnumerable<Item>;

public interface IMyController {
    public Task<GetItemsResponse> GetItems();
}

不足：终端用户在使用该接口时，必须在自己的代码中重复定义相同的别名，体验较差。

方案2：全局别名 #

使用全局别名覆盖整个项目：

global using GetItemsResponse = IEnumerable<Item>;

不足：在多版本API场景中会出现命名冲突，不同版本的GetItemsResponse对应不同的Item类型时无法共存：

global using GetItemsResponse = IEnumerable<ItemV1>;
global using GetItemsResponse = IEnumerable<ItemV2>; // 命名冲突！

namespace My.API.v1 {
    public interface IMyController {
        public Task<IEnumerable<ItemV1>> GetItems(); // 无法使用GetItemsResponse
    }
}

namespace My.API.v2 {
    public interface IMyController {
        public Task<IEnumerable<ItemV2>> GetItems(); // 无法使用GetItemsResponse
    }
}

方案3：继承集合类型 #

通过继承List<T>定义新类型：

public class GetItemsResponse : List<Item> {
    // 需要手动实现多个构造函数及方法，冗余繁琐
}

不足：必须重新实现父类的诸多构造函数和方法，代码冗余且容易出错。

优雅解决方案：命名空间级局部别名 #

在C# 10及以上版本中，我们可以将using别名定义在命名空间内部，让别名的作用域仅限于当前命名空间，完美解决多版本冲突问题，同时无需终端用户重复定义别名。

版本v1的实现 #

namespace My.API.v1;

// 别名作用域仅限于My.API.v1命名空间
using GetItemsResponse = IEnumerable<ItemV1>;

public interface IMyController {
    public Task<GetItemsResponse> GetItems();
}

版本v2的实现 #

namespace My.API.v2;

// 别名作用域仅限于My.API.v2命名空间，与v1的别名无冲突
using GetItemsResponse = IEnumerable<ItemV2>;

public interface IMyController {
    public Task<GetItemsResponse> GetItems();
}

终端用户使用方式 #

终端用户只需引用对应版本的命名空间，即可直接使用语义化的GetItemsResponse类型，无需额外定义：

using My.API.v1;

public class Client {
    public async Task CallApi(IMyController controller) {
        GetItemsResponse response = await controller.GetItems();
        // 直接使用response，无需关心底层是IEnumerable<ItemV1>
    }
}

进阶优化（C# 11+） #

如果需要更严格的类型隔离，可以使用**readonly record struct**作为包装器，仅暴露必要的接口，完全隐藏底层集合类型：

namespace My.API.v1;

public readonly record struct GetItemsResponse(IEnumerable<ItemV1> Items);

public interface IMyController {
    public Task<GetItemsResponse> GetItems();
}

// 控制器实现
public class MyController : IMyController {
    public async Task<GetItemsResponse> GetItems() {
        var items = new List<ItemV1> { /* 初始化数据 */ };
        return new GetItemsResponse(items);
    }
}

这种方式不仅提供了语义化的类型名，还通过包装器完全隔离了底层集合类型，同时readonly record struct是值类型，性能开销极低，代码也非常紧凑。

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