TypeScript类实现含可选字段接口的约束问题及方案咨询

我想要创建一个实现含可选字段接口的类，要求类必须声明这些可选字段，但当前TypeScript中，类实现该接口时不声明字段也不会报错。示例代码如下：

class User {
  constructor(name: string, age: number) {}
}

interface Paginatable<TEntity> {
  page?: number;
  perPage?: number;
  filterField?: keyof TEntity;
  filterValue?: TEntity[keyof TEntity];
}

class PaginatedUser implements Paginatable<User> {
  // 未声明字段但无报错...
}

我原本猜测是因为接口字段为可选，类可自由选择是否声明，但我认为实现接口时应强制类声明这些可选字段，显然这个假设不成立。因此有两个问题：

1. 请解释TypeScript此行为的原因，以及我的假设存在哪些错误？
2. 如何约束类必须声明这些可选字段？

补充背景：实际场景中该类用于GraphQL API的类型注解，示例代码如下：

interface FilterableEntityInput<TOrderFields, TSearchFields> {
  page?: number;
  itemsPerPage?: number;
  orderBy?: OrderByFilter;
  filterValue?: string;
  orderByField?: TOrderFields;
  filterField?: TSearchFields;
}

@InputType()
export class FilterTagInput
  extends BaseFilterInput
  implements
    Partial<EntityFilterInput<TagEntity>>,
    FilterableEntityInput<TagEntityOrderableFields, TagEntitySearchableFields>
{
  @Field(() => TagEntityOrderableFields, { nullable: true })
  orderByField?: TagEntityOrderableFields;

  @Field(() => TagEntitySearchableFields, { nullable: true })
  filterField?: TagEntitySearchableFields;
}

1. TypeScript行为原因及假设错误 #

TypeScript中接口的可选字段（带?）核心语义是：该字段可以不存在，或存在时符合对应类型约束。类实现接口的本质是保证类的实例结构兼容接口的类型要求——如果接口字段是可选的，类不声明该字段完全符合规则，因为实例缺失该字段本身就是可选字段允许的情况之一。

你的假设错误在于混淆了可选字段的设计逻辑：你认为实现接口就必须声明所有字段（包括可选字段），但TypeScript的接口约束是“结构兼容”而非“强制声明所有成员”，对于可选字段，只要类的实例不会出现类型不匹配的该字段，就视为满足接口要求。

另外，TypeScript采用结构类型系统（鸭子类型），只要两个类型的结构兼容就会被认为匹配，这也是缺失可选字段不报错的核心原因。

2. 约束类必须声明可选字段的方法 #

要强制类声明接口中的可选字段，需要先将接口的可选字段转为必填字段，再让类实现转换后的类型，具体方案如下：

方法1：使用Required工具类型 #

Required<T>会把类型T中所有可选字段转为必填字段，让类实现这个转换后的类型，就能强制声明所有字段：

interface Paginatable<TEntity> {
  page?: number;
  perPage?: number;
  filterField?: keyof TEntity;
  filterValue?: TEntity[keyof TEntity];
}

// 生成所有字段必填的类型
type PaginatableRequired<T> = Required<Paginatable<T>>;

class PaginatedUser implements PaginatableRequired<User> {
  // 必须显式声明所有字段，可保留?标记允许赋值为undefined
  page?: number;
  perPage?: number;
  filterField?: keyof User;
  filterValue?: User[keyof User];

  constructor() {
    // 可初始化字段为undefined，满足类型要求
    this.page = undefined;
    this.perPage = undefined;
  }
}

这里字段可以保留?（允许赋值为undefined），但必须显式声明，否则TypeScript会报错。

方法2：自定义工具类型（针对部分字段） #

如果只需要强制声明部分可选字段，可以自定义工具类型指定要转为必填的字段：

// 自定义工具类型：将T中的K字段转为必填，其余保持原样
type MakeRequired<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;

// 仅将Paginatable中的page和perPage转为必填
type PaginatablePartialRequired<T> = MakeRequired<Paginatable<T>, 'page' | 'perPage'>;

class PaginatedUser implements PaginatablePartialRequired<User> {
  // 必须声明page和perPage
  page?: number;
  perPage?: number;
  // filterField和filterValue仍为可选，可不声明
}

针对GraphQL场景的适配 #

在你的GraphQL场景中，需要用@Field装饰器标记字段，因此必须显式声明所有字段。结合Required工具类型可以实现约束：

interface FilterableEntityInput<TOrderFields, TSearchFields> {
  page?: number;
  itemsPerPage?: number;
  orderBy?: OrderByFilter;
  filterValue?: string;
  orderByField?: TOrderFields;
  filterField?: TSearchFields;
}

// 生成所有字段必填的类型
type FilterableEntityInputRequired<T1, T2> = Required<FilterableEntityInput<T1, T2>>;

@InputType()
export class FilterTagInput
  extends BaseFilterInput
  implements
    Partial<EntityFilterInput<TagEntity>>,
    FilterableEntityInputRequired<TagEntityOrderableFields, TagEntitySearchableFields>
{
  @Field(() => Int, { nullable: true })
  page?: number;

  @Field(() => Int, { nullable: true })
  itemsPerPage?: number;

  @Field(() => OrderByFilter, { nullable: true })
  orderBy?: OrderByFilter;

  @Field(() => String, { nullable: true })
  filterValue?: string;

  @Field(() => TagEntityOrderableFields, { nullable: true })
  orderByField?: TagEntityOrderableFields;

  @Field(() => TagEntitySearchableFields, { nullable: true })
  filterField?: TagEntitySearchableFields;
}

这种方式既通过TypeScript强制声明了所有字段，又通过@Field的nullable: true保持了GraphQL层面的可选性，两者不冲突。

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