From 9423f15f2919f6f8aa02ae8d899d9741fcf59485 Mon Sep 17 00:00:00 2001
From: wangxiaogang <1433729587@qq.com>
Date: Mon, 8 Jun 2026 11:25:03 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20DEV.md=20=E2=80=94?=
 =?UTF-8?q?=20API=20=E8=B0=83=E7=94=A8=E8=A7=84=E8=8C=83=E5=92=8C=E9=A1=B5?=
 =?UTF-8?q?=E9=9D=A2=E5=8A=A0=E8=BD=BD=E6=A8=A1=E5=BC=8F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- request 函数正确调用格式说明
- 页面数据加载标准模式（initialLoaded 守卫）
---
 DEV.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/DEV.md b/DEV.md
index 392ef01..85d190d 100644
--- a/DEV.md
+++ b/DEV.md
@@ -33,6 +33,47 @@
 - API 地址统一在 `config.ts` 中配置，不要在各文件中硬编码
 - 头像等用户文件 URL 只存文件名，前端拼接 `API_BASE + 路径 + 文件名`
 
+## API 调用规范
+
+### request 函数调用格式
+
+`request` 函数**只接受一个对象参数**，格式为 `{ url, method?, data? }`。
+
+```typescript
+// ✅ 正确
+request({ url: '/feedback', data: params })
+request({ url: '/config' })
+request({ url: '/feedback', method: 'POST', data })
+
+// ❌ 错误 — 会导致 URL 拼接为 /apiundefined
+request('/feedback', { params })
+request('/config', { method: 'PUT', data })
+```
+
+**原因**：`request` 函数签名是 `request<T>(options: RequestOptions): Promise<T>`，第一个参数是 options 对象，不支持分开传 url 和 options。
+
+### 页面数据加载模式
+
+```typescript
+const initialLoaded = ref(false)
+
+onMounted(async () => {
+  await waitForReady()
+  await loadData()
+  initialLoaded.value = true
+})
+
+// onShow 时静默刷新，但必须有 initialLoaded 守卫
+onShow(() => {
+  if (initialLoaded.value) loadData(true)
+})
+
+onPullDownRefresh(async () => {
+  await loadData()
+  uni.stopPullDownRefresh()
+})
+```
+
 ## Never 规则
 
 - Never 修改 dist/ 目录