---
name: "declare-request-usage"
description: "规范使用 declareRequest 声明 API 并在组件中通过 props 调用的模式。当新增/调用 declareRequest 声明的接口时，必须遵循此规范。"
---

# declareRequest 使用规范

## 核心原则

**不要直接 import `declareRequest` 声明的函数并直接调用。** 必须通过 `Connect` 注入的 `props` 访问。

## 正确步骤

### 1. 声明 API (在 `src/api/` 下)

```js
// src/api/xxx/index.js
import { declareRequest } from "@cqsjjb/jjb-dva-runtime";

export const someApi = declareRequest(
  "xxxLoading",          // loading key，与 namespace 同名前缀
  "Get > /path/to/api",  // 请求方式与路径
  "someData: [] | res.data || []",  // 响应数据映射（可选）
);
```

### 2. 使用 API (在页面组件中)

**正确**：通过 `Connect` 注入的 `props` 访问

```jsx
import { Connect } from "@cqsjjb/jjb-dva-runtime";
import { NS_XXX } from "~/enumerate/namespace";

function MyPage(props) {
  const handleLoad = () => {
    // ✅ 通过 props 调用
    props.someApi(params).then((res) => {
      // 处理结果
    });
  };
}

export default Connect(
  [NS_XXX],  // 传入正确的 namespace
  true,
)(MyPage);
```

**正确**：父组件通过 props 传递给子组件

```jsx
// 父组件
function Parent(props) {
  return <Child someApi={props.someApi} />;
}

// 子组件通过 props 接收
function Child({ someApi }) {
  const handleLoad = () => {
    someApi(params);  // ✅ 正确
  };
}
```

**错误**：直接 import 并调用

```jsx
// ❌ 错误！不要这样做
import { someApi } from "~/api/xxx";

function MyComponent() {
  // ❌ someApi 不是可调用的函数
  someApi(params);
}
```

## 为什么

`declareRequest` 注册的是 Redux action，需要通过 `Connect` 绑定到组件的 props 后才能正常工作。直接 import 得到的不是可调用的函数，会导致 `is not a function` 错误。

## 检查清单

- [ ] API 声明在 `src/api/` 下的对应文件中
- [ ] `declareRequest` 的 loading key 与 namespace 的 loading 前缀一致
- [ ] 组件通过 `Connect([NS_XXX], true)` 连接
- [ ] 通过 `props.apiName(params)` 调用，而非直接 import 调用
- [ ] 子组件需要的 API 函数通过 props 从父组件传入