ZYT/zyt

Fork 0

Files

T

Your Name 38ad60f4bb 更新

2026-03-11 09:49:47 +08:00

6.0 KiB

Raw Blame History

用户搜索 API 文档

概述

新增了用户/患者搜索 API 端点，用于在创建订单等场景中快速搜索用户。

API 端点

搜索用户

请求

GET /user.user/search

参数

{
  "keyword": "张三",           // 搜索关键词（必填）
  "page_no": 1,               // 页码（可选，默认1）
  "page_size": 10             // 每页数量（可选，默认10）
}

搜索字段

nickname - 用户昵称
mobile - 手机号码
account - 账号

响应

{
  "code": 1,
  "msg": "success",
  "data": {
    "lists": [
      {
        "id": 1,
        "nickname": "张三",
        "mobile": "13800138000",
        "account": "zhangsan",
        "avatar": "https://example.com/avatar.jpg"
      }
    ],
    "count": 1,
    "page_no": 1,
    "page_size": 10
  }
}

实现细节

后端实现

文件: server/app/adminapi/controller/user/UserController.php

/**
 * @notes 搜索用户（用于创建订单等场景）
 * @return \think\response\Json
 */
public function search()
{
    $keyword = $this->request->get('keyword', '');
    $page_no = $this->request->get('page_no', 1);
    $page_size = $this->request->get('page_size', 10);

    if (empty($keyword)) {
        return $this->success('', ['lists' => [], 'count' => 0]);
    }

    $offset = ($page_no - 1) * $page_size;
    
    $lists = \app\common\model\user\User::where('nickname|mobile|account', 'like', '%' . $keyword . '%')
        ->field(['id', 'nickname', 'mobile', 'account', 'avatar'])
        ->limit($offset, $page_size)
        ->order('id desc')
        ->select()
        ->toArray();

    $count = \app\common\model\user\User::where('nickname|mobile|account', 'like', '%' . $keyword . '%')
        ->count();

    return $this->success('', [
        'lists' => $lists,
        'count' => $count,
        'page_no' => $page_no,
        'page_size' => $page_size
    ]);
}

前端实现

文件: admin/src/api/order.ts

// 搜索用户/患者
export function searchPatients(params: any) {
    return request.get({ url: '/user.user/search', params })
}

使用示例:

import { searchPatients } from '@/api/order'

const res = await searchPatients({
    keyword: '张三',
    page_no: 1,
    page_size: 10
})

使用场景

1. 创建订单时搜索患者

在订单创建弹窗中，患者输入框使用远程搜索：

<el-select
    v-model="createForm.patient_id"
    placeholder="请选择患者"
    filterable
    remote
    :remote-method="searchPatients"
    :loading="patientLoading"
>
    <el-option
        v-for="item in patientList"
        :key="item.id"
        :label="`${item.nickname} (${item.mobile})`"
        :value="item.id"
    />
</el-select>

2. 组件中的使用

const patientLoading = ref(false)
const patientList = ref<any[]>([])

const searchPatients = async (query: string) => {
    if (!query) {
        patientList.value = []
        return
    }
    try {
        patientLoading.value = true
        const res = await searchPatientsAPI({
            keyword: query,
            page_no: 1,
            page_size: 10
        })
        patientList.value = res?.lists || []
    } finally {
        patientLoading.value = false
    }
}

特性

✅ 多字段搜索 - 支持按昵称、手机号、账号搜索 ✅ 分页支持 - 支持分页查询 ✅ 性能优化 - 只返回必要字段 ✅ 模糊匹配 - 支持模糊搜索 ✅ 排序 - 按 ID 倒序排列

返回字段说明

字段	类型	说明
id	int	用户ID
nickname	string	用户昵称
mobile	string	手机号码
account	string	账号
avatar	string	头像URL

权限

此 API 端点需要管理员权限，受后端权限系统控制。

对比旧方案

旧方案

使用 /user.user/lists 获取完整用户列表
需要获取所有用户数据
性能较差

新方案

使用 /user.user/search 搜索用户
只返回匹配的用户
支持分页
性能更好

示例请求

搜索昵称为"张三"的用户

curl -X GET "http://localhost:8000/user.user/search?keyword=张三&page_no=1&page_size=10" \
  -H "token: your_admin_token"

搜索手机号为"138"开头的用户

curl -X GET "http://localhost:8000/user.user/search?keyword=138&page_no=1&page_size=10" \
  -H "token: your_admin_token"

搜索账号为"zhang"的用户

curl -X GET "http://localhost:8000/user.user/search?keyword=zhang&page_no=1&page_size=10" \
  -H "token: your_admin_token"

响应示例

成功响应

{
  "code": 1,
  "msg": "success",
  "data": {
    "lists": [
      {
        "id": 1,
        "nickname": "张三",
        "mobile": "13800138000",
        "account": "zhangsan",
        "avatar": "https://example.com/avatar.jpg"
      },
      {
        "id": 2,
        "nickname": "张四",
        "mobile": "13800138001",
        "account": "zhangsi",
        "avatar": "https://example.com/avatar2.jpg"
      }
    ],
    "count": 2,
    "page_no": 1,
    "page_size": 10
  }
}

空结果响应

{
  "code": 1,
  "msg": "success",
  "data": {
    "lists": [],
    "count": 0,
    "page_no": 1,
    "page_size": 10
  }
}

无关键词响应

{
  "code": 1,
  "msg": "success",
  "data": {
    "lists": [],
    "count": 0
  }
}

注意事项

关键词必填 - 必须提供搜索关键词，否则返回空列表
最少一个字符 - 建议在用户输入至少一个字符后才发起搜索
分页参数 - page_no 和 page_size 为可选参数，有默认值
性能考虑 - 搜索结果默认返回 10 条，可根据需要调整 page_size

创建日期: 2024-03-10 版本: 1.0.0 状态: ✅ 完成

6.0 KiB Raw Blame History Unescape Escape