lobe-data-fetching

name	lobe-data-fetching
version	0.2.0
author	OpenClaw-Foreign
description	---
permissions	[]

--- name: lobe-data-fetching description: Lobe Chat 前端数据获取架构设计：Zustand、SWR、缓存策略最佳实践

---

name: data-fetching-architecture description: 'LobeHub data-fetching pipeline guide. Use for service layer, Zustand store, SWR, lambdaClient, useClientDataSWR, useFetchXxx hooks, or migrating useEffect fetches.' user-invocable: false

LobeHub Data Fetching Architecture

Related: store-data-structures covers List vs Detail data shape rationale (Map vs Array).

Architecture Overview

鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?鈹? Component  鈹?鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹攢鈹€鈹€鈹€鈹€鈹€鈹?       鈹?1. Call useFetchXxx hook from store
       鈫?鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?鈹? Zustand Store   鈹?鈹? (State + Hook)  鈹?鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?       鈹?2. useClientDataSWR calls service
       鈫?鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?鈹? Service Layer   鈹?鈹? (xxxService)    鈹?鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?       鈹?3. Call lambdaClient
       鈫?鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?鈹? lambdaClient    鈹?鈹? (TRPC Client)   鈹?鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?```

## Core Principles

### 鉁?DO

1. **Use Service Layer** for all API calls
2. **Use Store SWR Hooks** for data fetching (not useEffect)
3. **Use proper data structures** 鈥?see `store-data-structures` skill for List vs Detail patterns
4. **Use lambdaClient.mutate** for write operations (create/update/delete)
5. **Use lambdaClient.query** only inside service methods
6. **Naming convention** 鈥?read hooks are `useFetchXxx`, cache invalidation helpers are `refreshXxx` (e.g. `useFetchBenchmarks` / `refreshBenchmarks`). Mutations then chain `refreshXxx()` after the service call.

### 鉂?DON'T

1. **Never use useEffect** for data fetching
2. **Never call lambdaClient** directly in components or stores
3. **Never use useState** for server data
4. **Never mix data structure patterns** 鈥?follow `store-data-structures` skill

---

## Layer 1: Service Layer

### Purpose

- Encapsulate all API calls to lambdaClient
- Provide clean, typed interfaces
- Single source of truth for API operations

### Service Structure

```typescript
// src/services/agentEval.ts
class AgentEvalService {
  // Query methods - READ operations
  async listBenchmarks() {
    return lambdaClient.agentEval.listBenchmarks.query();
  }

  async getBenchmark(id: string) {
    return lambdaClient.agentEval.getBenchmark.query({ id });
  }

  // Mutation methods - WRITE operations
  async createBenchmark(params: CreateBenchmarkParams) {
    return lambdaClient.agentEval.createBenchmark.mutate(params);
  }

  async updateBenchmark(params: UpdateBenchmarkParams) {
    return lambdaClient.agentEval.updateBenchmark.mutate(params);
  }

  async deleteBenchmark(id: string) {
    return lambdaClient.agentEval.deleteBenchmark.mutate({ id });
  }
}

export const agentEvalService = new AgentEvalService();

Service Guidelines

1. One service per domain (e.g., agentEval, ragEval, aiAgent)
2. Export singleton instance (export const xxxService = new XxxService())
3. Method names match operations (list, get, create, update, delete)
4. Clear parameter types (use interfaces for complex params)

---

Layer 2: Store with SWR Hooks

Purpose

• Manage client-side state
• Provide SWR hooks for data fetching
• Handle cache invalidation

State Structure

// src/store/eval/slices/benchmark/initialState.ts
export interface BenchmarkSliceState {
  // List data - simple array
  benchmarkList: AgentEvalBenchmarkListItem[];
  benchmarkListInit: boolean;

  // Detail data - map for caching
  benchmarkDetailMap: Record<string, AgentEvalBenchmark>;
  loadingBenchmarkDetailIds: string[];

  // Mutation states
  isCreatingBenchmark: boolean;
  isUpdatingBenchmark: boolean;
  isDeletingBenchmark: boolean;
}

For complete initialState, reducer, and internal dispatch patterns, see the store-data-structures skill.

Actions

// src/store/eval/slices/benchmark/action.ts
const FETCH_BENCHMARKS_KEY = 'FETCH_BENCHMARKS';
const FETCH_BENCHMARK_DETAIL_KEY = 'FETCH_BENCHMARK_DETAIL';

export interface BenchmarkAction {
  // SWR Hooks - for data fetching
  useFetchBenchmarks: () => SWRResponse;
  useFetchBenchmarkDetail: (id?: string) => SWRResponse;

  // Refresh methods - for cache invalidation
  refreshBenchmarks: () => Promise<void>;
  refreshBenchmarkDetail: (id: string) => Promise<void>;

  // Mutation actions
  createBenchmark: (params: CreateParams) => Promise<any>;
  updateBenchmark: (params: UpdateParams) => Promise<void>;
  deleteBenchmark: (id: string) => Promise<>;

  
  :  ;
  :  ;
}

  : <, , [], > =  ({
  
  : 
    (,  agentEvalService.(), {
      :  {
        ({ : data, :  }, , );
      },
    }),

  
  : 
    (
      id ? [, id] : ,
       agentEvalService.(id!),
      {
        :  {
          ().({
            : ,
            : id!,
            : data,
          });
          ().(id!, );
        },
      },
    ),

  
  :  (),
  :  ([, id]),

  
  :  (params) => {
    ({ :  }, , );
     {
       result =  agentEvalService.(params);
       ().();
       result;
    }  {
      ({ :  }, , );
    }
  },

  
  :  (params) => {
     { id } = params;

    
    ().({
      : ,
      id,
      : params,
    });
    
    ().(id, );

     {
      
       agentEvalService.(params);
      
       ().();
       ().(id);
    }  {
      ().(id, );
    }
  },

  
  :  (id) => {
    ().({ : , id });
    ().(id, );

     {
       agentEvalService.(id);
       ().();
    }  {
      ().(id, );
    }
  },

  
  :  {
     currentMap = ().;
     nextMap = (currentMap, payload);

    
     ((nextMap, currentMap)) ;
    ({ : nextMap }, , );
  },

  
  :  {
    (
       ({
        : loading
          ? [...state., id]
          : state..( i !== id),
      }),
      ,
      ,
    );
  },
});

Store Guidelines

1. SWR keys as constants at top of file
2. useClientDataSWR for all data fetching (never useEffect)
3. onSuccess callback updates store state
4. Refresh methods use mutate() to invalidate cache
5. Loading states in initialState, updated in onSuccess
6. Mutations call service, then refresh relevant cache

---

Layer 3: Component Usage

Fetching List Data

// 鉁?CORRECT
const BenchmarkList = () => {
  // 1. Get the hook from store
  const useFetchBenchmarks = useEvalStore((s) => s.useFetchBenchmarks);

  // 2. Get list data
  const benchmarks = useEvalStore((s) => s.benchmarkList);
  const isInit = useEvalStore((s) => s.benchmarkListInit);

  // 3. Call the hook (SWR handles the data fetching)
  useFetchBenchmarks();

  // 4. Use the data
  if (!isInit) return <Loading />;
  return (
    <div>
      <h2>Total: {benchmarks.length}</h2>
      {benchmarks.map((b) => (
        <BenchmarkCard key={b.id} {...b} />
      ))}
    </div>
  );
};

Fetching Detail Data

// 鉁?CORRECT
const BenchmarkDetail = () => {
  const { benchmarkId } = useParams<{ benchmarkId: string }>();

  const useFetchBenchmarkDetail = useEvalStore((s) => s.useFetchBenchmarkDetail);

  // Detail from map
  const benchmark = useEvalStore((s) =>
    benchmarkId ? s.benchmarkDetailMap[benchmarkId] : undefined,
  );

  // Per-item loading
  const isLoading = useEvalStore((s) =>
    benchmarkId ? s.loadingBenchmarkDetailIds.includes(benchmarkId) : false,
  );

  useFetchBenchmarkDetail(benchmarkId);

  if (!benchmark) return <Loading />;
  return (
    <div>
      <h1>{benchmark.name}</h1>
      <p>{benchmark.description}</p>
      {isLoading && <Spinner />}
    </div>
  );
};

Using Selectors (Recommended)

// src/store/eval/slices/benchmark/selectors.ts
export const benchmarkSelectors = {
  getBenchmarkDetail: (id: string) => (s: EvalStore) => s.benchmarkDetailMap[id],
  isLoadingBenchmarkDetail: (id: string) => (s: EvalStore) =>
    s.loadingBenchmarkDetailIds.includes(id),
};

// Component with selectors
const BenchmarkDetail = () => {
  const { benchmarkId } = useParams();
  const useFetchBenchmarkDetail = useEvalStore((s) => s.useFetchBenchmarkDetail);
  const benchmark = useEvalStore(benchmarkSelectors.getBenchmarkDetail(benchmarkId!));

  useFetchBenchmarkDetail(benchmarkId);

  return <div>{benchmark && <h1>{benchmark.name}</h1>}</div>;
};

Anti-pattern

// 鉂?WRONG 鈥?Don't use useEffect for data fetching
const BenchmarkList = () => {
  const [data, setData] = useState([]);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    setLoading(true);
    lambdaClient.agentEval.listBenchmarks
      .query()
      .then(setData)
      .finally(() => setLoading(false));
  }, []);

  return <div>...</div>;
};

Mutations in Components

// Create 鈥?global mutation flag drives form loading
const CreateBenchmarkModal = () => {
  const createBenchmark = useEvalStore((s) => s.createBenchmark);
  const isCreating = useEvalStore((s) => s.isCreatingBenchmark);

  const handleSubmit = async (values) => {
    try {
      // Optimistic update + refresh happen inside createBenchmark
      await createBenchmark(values);
      message.success('Created successfully');
      onClose();
    } catch (error) {
      message.error('Failed to create');
    }
  };

  return (
    <Form onSubmit={handleSubmit} loading={isCreating}>
      ...
    </Form>
  );
};

// Update / delete 鈥?per-item loading so only the row being mutated spins
const BenchmarkItem = ({ id }: { id: string }) => {
  const updateBenchmark = useEvalStore((s) => s.updateBenchmark);
  const deleteBenchmark = ( s.);
   isLoading = (benchmarkSelectors.(id));

    =  () => {
     ({ id, ...data });
  };

    =  () => {
     (id);
  };

   (
    
  );
};

Why two patterns: create has no id yet, so a single isCreatingXxx flag is enough. Update/delete target a specific row, so global flags would freeze unrelated rows 鈥?keep per-item state in loadingXxxIds.

---

Need a fuller worked example?

The canonical Benchmark example above is the one to copy for a flat list + detail map. If you need to maintain a list keyed by a parent id (e.g. datasetMap[benchmarkId] because the same shape appears under multiple parents), read references/walkthrough.md 鈥?it walks through the full 6 steps (service 鈫?reducer 鈫?slice 鈫?store wiring 鈫?selectors 鈫?component) for that variant.

---

Common Patterns

Pattern 1: Pagination

Cache key array must include every parameter that should trigger a refetch.

useFetchTestCases: (params: { datasetId: string; limit: number; offset: number }) =>
  useClientDataSWR(
    params.datasetId ? [FETCH_TEST_CASES_KEY, params.datasetId, params.limit, params.offset] : null,
    () => agentEvalService.listTestCases(params),
    {
      onSuccess: (data) =>
        set({
          testCaseList: data.data,
          testCaseTotal: data.total,
          isLoadingTestCases: false,
        }),
    },
  );

Pattern 2: Dependent Fetching

Both hooks run in parallel 鈥?SWR dedupes, no manual sequencing needed.

const BenchmarkDetail = () => {
  const { benchmarkId } = useParams();
  const useFetchBenchmarkDetail = useEvalStore((s) => s.useFetchBenchmarkDetail);
  const useFetchDatasets = useEvalStore((s) => s.useFetchDatasets);

  useFetchBenchmarkDetail(benchmarkId);
  useFetchDatasets(benchmarkId);

  return <div>...</div>;
};

Pattern 3: Conditional Fetching

Pass undefined to disable the hook entirely.

// only fetch when modal is open AND id present
useFetchDatasetDetail(open && datasetId ? datasetId : undefined);

Pattern 4: Cross-domain Refresh

deleteBenchmark: async (id) => {
  await agentEvalService.deleteBenchmark(id);
  await get().refreshBenchmarks();
  await get().refreshDatasets(id); // related cache invalidated too
};

---

Migration Guide: useEffect 鈫?Store SWR

Before (鉂?Wrong)

const TestCaseList = ({ datasetId }: Props) => {
  const [data, setData] = useState<any[]>([]);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    setLoading(true);
    lambdaClient.agentEval.listTestCases
      .query({ datasetId })
      .then((r) => setData(r.data))
      .finally(() => setLoading(false));
  }, [datasetId]);

  return <Table data={data} loading={loading} />;
};

After (鉁?Correct)

// 1. Add service method
class AgentEvalService {
  async listTestCases(params: { datasetId: string }) {
    return lambdaClient.agentEval.listTestCases.query(params);
  }
}

// 2. Add store slice hook
export const createTestCaseSlice: StateCreator<...> = (set) => ({
  useFetchTestCases: (params) =>
    useClientDataSWR(
      params.datasetId ? [FETCH_TEST_CASES_KEY, params.datasetId] : null,
      () => agentEvalService.listTestCases(params),
      {
        onSuccess: (data) =>
          set({ testCaseList: data.data, isLoadingTestCases: false }),
      },
    ),
});

// 3. Component reads from store
const TestCaseList = ({ datasetId }: Props) => {
  const useFetchTestCases = useEvalStore((s) => s.useFetchTestCases);
  const data = useEvalStore( s.);
   loading = ( s.);

  ({ datasetId });

   ;
};

---

Troubleshooting

Symptom	Check
Data never loads	Hook called? Key not null/undefined? Network tab shows request?
Stale data after mutation	Did refreshXxx run? Cache key matches what the hook uses?
Loading state stuck true	onSuccess writes loading=false? Promise rejected silently?
Detail map missing an entry	Reducer dispatch ran? isEqual short-circuited on stale data?

---

Summary Checklist

When adding new data fetching:

Step 1: Types & State

See store-data-structures for details.

• Define types in @lobechat/types: Detail type + List item type
• State structure: xxxList: XxxListItem[], xxxDetailMap: Record<string, Xxx>, loadingXxxDetailIds: string[]
• Reducer if optimistic updates are needed

Step 2: Service Layer

• Create service in src/services/xxxService.ts
• Methods: listXxx(), getXxx(id), createXxx(), updateXxx(), deleteXxx()

Step 3: Store Actions

• initialState.ts with state structure
• action.ts with:
  • useFetchXxxList(), useFetchXxxDetail(id) 鈥?SWR hooks
  • refreshXxxList(), refreshXxxDetail(id) 鈥?cache invalidation
  • CRUD methods calling service
  • internal_dispatch, internal_updateLoading if using reducer
• selectors.ts (optional but recommended)
• Integrate slice into main store + initialState

Step 4: Component Usage

• Use store hooks (NOT useEffect)
• List pages: access xxxList array
• Detail pages: access xxxDetailMap[id]
• Use loading states for UI feedback

Mental model: Types 鈫?Service 鈫?Reducer 鈫?Slice 鈫?Component 馃幆

---

Related Skills

• store-data-structures 鈥?How to structure List and Detail data in stores
• zustand 鈥?General Zustand patterns and best practices