React中如何实现支持动态字段、筛选排序的类型安全API查询？

问题背景 #

在使用DRF做后端、React（TypeScript）做前端的项目中，查询API时总会碰到三个痛点：

• API响应没有原生类型支持，前端无法获得类型提示，容易出现类型错误
• 无法精确指定API返回的字段，要么返回全量数据造成冗余，要么后端硬编码接口适配不同场景
• 筛选、排序操作缺乏类型安全，字段名拼写错误要到运行时才会暴露

理想效果 #

希望能实现类似以下的类型安全查询，同时解决上述三个问题：

// 以User模型为例
export function UserComponent(props: ...){

  // `data`自动推断为Pick<User, "email" | "lastActive">类型
  const data = myCustomAPIFetch<User>({
    model: User,
    fields: ["email", "lastActive"],
    filters: {
      firstName: "Linus"
    },
    sort: ["lastActive"]
  })

  return (...)
}

这个方案的核心优势：

• 返回数据类型自动推导，前端获得完整类型提示
• 字段、筛选、排序都基于TS类型约束，避免非法字段操作
• 精确指定返回字段，减少不必要的数据传输

现有方案的局限性 #

之前调研过几种方案，但都无法完全满足需求：

• GraphQL：能解决类型提示和字段指定问题，但每个筛选/排序逻辑都要单独编写查询和解析器，维护成本高，动态性不足
• Protobuf：跨语言类型支持强，但Schema是静态的，要返回不同字段组合就得创建新的消息类型，扩展性差
• tRPC：仅适用于纯TS技术栈，且无法动态指定返回字段，也难以实现通用的类型安全筛选排序

可行实现思路 #

结合DRF和React TS的特性，可以通过前后端协同来实现目标：

后端（DRF）实现 #

1. 动态字段返回：使用DRF的DynamicFieldsMixin，允许前端通过fields查询参数指定需要返回的字段。示例：

   from rest_framework import viewsets
   from rest_framework.mixins import DynamicFieldsMixin
   
   class UserViewSet(DynamicFieldsMixin, viewsets.ModelViewSet):
       queryset = User.objects.all()
       serializer_class = UserSerializer
   

   前端传入?fields=email,lastActive，接口就只返回这两个字段。

2. 动态过滤与排序：自定义过滤后端，支持前端通过filters和sort参数传递条件：

   import json
   from rest_framework.filters import BaseFilterBackend
   
   class DynamicFilterBackend(BaseFilterBackend):
       def filter_queryset(self, request, queryset, view):
           filters = request.query_params.get('filters', '{}')
           try:
               filter_dict = json.loads(filters)
               valid_fields = [f.name for f in view.queryset.model._meta.fields]
               filter_kwargs = {k: v for k, v in filter_dict.items() if k in valid_fields}
               queryset = queryset.filter(**filter_kwargs)
           except json.JSONDecodeError:
               pass
           
           sort = request.query_params.get('sort', '')
           if sort:
               valid_fields = [f.name for f in view.queryset.model._meta.fields]
               sort_fields = [s.strip() for s in sort.split(',')]
               valid_sort_fields = [s for s in sort_fields if s.lstrip('-') in valid_fields]
               queryset = queryset.order_by(*valid_sort_fields)
           
           return queryset
   

   在ViewSet中配置这个过滤后端即可支持动态筛选和排序。

3. 自动生成TS类型：使用drf-spectacular生成OpenAPI Schema，再通过openapi-typescript工具将Schema转换成TS类型定义，前端直接复用这些类型，确保前后端类型一致。

前端（React TS）实现 #

封装通用的myCustomAPIFetch工具函数，利用TS泛型实现类型约束和自动推导：

import { User } from './generated-types'; // 从后端生成的类型文件导入

type FetchOptions<T> = {
  endpoint: string; // 比如'/api/users/'
  fields: Array<keyof T>;
  filters?: Partial<Record<keyof T, any>>;
  sort?: Array<keyof T>;
};

async function myCustomAPIFetch<T>(options: FetchOptions<T>): Promise<Pick<T, typeof options.fields[number]>> {
  const params = new URLSearchParams();
  
  // 处理字段参数
  params.append('fields', options.fields.join(','));
  
  // 处理筛选参数（转成JSON字符串）
  if (options.filters) {
    params.append('filters', JSON.stringify(options.filters));
  }
  
  // 处理排序参数
  if (options.sort) {
    params.append('sort', options.sort.join(','));
  }
  
  const response = await fetch(`${options.endpoint}?${params}`);
  const data = await response.json();
  
  return data as Pick<T, typeof options.fields[number]>;
}

// 组件中使用示例
export function UserComponent() {
  const [data, setData] = useState<Pick<User, 'email' | 'lastActive'> | null>(null);

  useEffect(() => {
    myCustomAPIFetch<User>({
      endpoint: '/api/users/',
      fields: ['email', 'lastActive'],
      filters: { firstName: 'Linus' },
      sort: ['-lastActive'] // 负号表示降序
    }).then(setData);
  }, []);

  return (
    <div>
      {data ? (
        <>
          <p>邮箱: {data.email}</p>
          <p>最后活跃: {data.lastActive}</p>
        </>
      ) : (
        <p>加载中...</p>
      )}
    </div>
  );
}

关键注意事项 #

• 后端必须对前端传入的字段、筛选条件做合法性校验，防止非法字段导致的报错或安全问题
• 类型生成过程要自动化，可以通过CI/CD流程在后端模型变更时自动更新前端类型文件
• 过滤逻辑可以扩展支持复杂条件（比如gt、lt等），前端对应的类型也要做适配，比如把filters的类型改为支持嵌套条件

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