跳至主要內容

QueryMapFacade 使用手册

游鹄君2026年3月6日大约 7 分钟phpopensourcephpfacade

QueryMapFacade 使用手册

版本: v1
作者: youhujun & xueer
更新日期: 2026-03-05

📖 概述

QueryMapFacade 是游鹄生态中用于微服务间映射表查询的专用门面服务。它提供了通过非业务ID查询映射表的 API 接口，支持跨服务的映射表查询功能。

核心特点

  • ✅ 模型映射管理：通过 modelMap 管理不同模型映射表的查询
  • ✅ 非业务ID查询：支持通过账号名、手机号等非业务ID字段查询
  • ✅ 模糊查询支持：支持模糊查询获取业务ID列表
  • ✅ DTO 参数封装：使用 DTO 对象封装请求参数
  • ✅ 日志记录：自动记录查询操作日志

适用场景

  • 微服务架构下跨服务查询映射表
  • 通过非业务ID（如手机号、邮箱）查询用户信息
  • 模糊查询获取符合条件的业务ID列表
  • 跨服务的订单、产品等数据查询

🔄 工作原理

查询流程

微服务API请求
    ↓
1. 接收 DTO 参数
   - model: 模型标识（JSON字符串）
   - field: 查询字段（JSON字符串）
   - value: 查询值（JSON字符串）
   - extra: 额外条件（JSON字符串，可选）
    ↓
2. 解析 JSON 参数
    ↓
3. 根据 model 查找对应的模型类
    ↓
4. 调用 ShardMapHelperFacade 查询映射表
    ↓
5. 返回查询结果
    ↓
6. 记录查询日志

模型映射配置

QueryMapFacadeService 中通过 $modelMap 管理模型映射：

private $modelMap = [
    'UserMap' => [
        'code' => 10,
        'handler' => function () {
            return UserMap::class;
        }
    ],
    // 'OrderMap' => [...],
    // 'ProductMap' => [...],
];

📚 方法详解

getShardInfoByNonBizId

通过非业务ID查询映射表，获取分片信息。

方法签名

public function getShardInfoByNonBizId(GetShardInfoDTO $getShardInfoDTO): array

参数说明

参数类型必填说明
$getShardInfoDTOGetShardInfoDTO是查询分片信息DTO对象

GetShardInfoDTO 字段说明

字段类型必填说明
modelstring是模型标识（JSON字符串，如 '"UserMap"'）
fieldstring是查询字段（JSON字符串，如 '"phone"'）
valuestring是查询值（JSON字符串，如 '"13800138000"'）

返回值

成功时返回：

[
    'code' => 0,
    'msg' => '查询成功',
    'data' => [
        'biz_id' => '276406781286953',
        'shard_db' => 'ds_0',
        'shard_table' => 'users_0',
        'shard_key' => 0,
        'base_table' => 'users'
    ]
]

未找到数据时 data 为 null。

异常处理

异常说明
BaseModelEmptyError模型未配置
ModelCodeEmptyError模型编码无效

getBizIdsByFuzzySearch

通过模糊查询获取业务ID列表。

方法签名

public function getBizIdsByFuzzySearch(GetBizIdsDTO $getBizIdsDTO): array

参数说明

参数类型必填说明
$getBizIdsDTOGetBizIdsDTO是模糊查询DTO对象

GetBizIdsDTO 字段说明

字段类型必填说明
modelstring是模型标识（JSON字符串，如 '"UserMap"'）
fieldstring是查询字段（JSON字符串，如 '"phone"'）
valuestring是查询值（JSON字符串，如 '"138%"'）
extrastring否额外条件（JSON字符串，如 '{"status":1}'）

返回值

成功时返回：

[
    'code' => 0,
    'msg' => '查询成功',
    'data' => [
        '276406781286953',
        '276406781286954',
        '276406781286955'
    ]
]

未找到数据时 data 为空数组 []。

异常处理

异常说明
BaseModelEmptyError模型未配置
ModelCodeEmptyError模型编码无效

💡 使用示例

示例1：通过手机号查询用户分片信息

use App\Facades\LaravelShardMap\V1\Api\Map\QueryMapFacade;
use App\DTOs\Api\V1\Map\GetShardInfoDTO;

class MapQueryController
{
    /**
     * 通过手机号查询用户分片信息（API接口）
     */
    public function getUserShardInfo(Request $request)
    {
        // 1. 创建 DTO
        $getShardInfoDTO = new GetShardInfoDTO();
        $getShardInfoDTO->set('model', json_encode('UserMap'));
        $getShardInfoDTO->set('field', json_encode('phone'));
        $getShardInfoDTO->set('value', json_encode($request->input('phone')));
        
        // 2. 执行查询
        try {
            $result = QueryMapFacade::getShardInfoByNonBizId($getShardInfoDTO);
            return $this->success($result);
        } catch (CommonException $e) {
            return $this->error($e->getMessage());
        }
    }
}

示例2：模糊查询用户列表

use App\Facades\LaravelShardMap\V1\Api\Map\QueryMapFacade;
use App\DTOs\Api\V1\Map\GetBizIdsDTO;

class MapQueryController
{
    /**
     * 模糊查询用户列表（API接口）
     */
    public function searchUsers(Request $request)
    {
        // 1. 创建 DTO
        $getBizIdsDTO = new GetBizIdsDTO();
        $getBizIdsDTO->set('model', json_encode('UserMap'));
        $getBizIdsDTO->set('field', json_encode('phone'));
        $getBizIdsDTO->set('value', json_encode($request->input('phone_prefix') . '%'));
        
        // 可选：添加额外条件
        if ($request->has('status')) {
            $getBizIdsDTO->set('extra', json_encode(['status' => $request->input('status')]));
        }
        
        // 2. 执行查询
        try {
            $result = QueryMapFacade::getBizIdsByFuzzySearch($getBizIdsDTO);
            return $this->success($result);
        } catch (CommonException $e) {
            return $this->error($e->getMessage());
        }
    }
}

🔒 内部处理逻辑

getShardInfoByNonBizId 处理流程

public function getShardInfoByNonBizId(GetShardInfoDTO $getShardInfoDTO)
{
    // 1. 获取 DTO 参数
    $jsonModel = $getShardInfoDTO->get('model');
    $jsonField = $getShardInfoDTO->get('field');
    $jsonValue = $getShardInfoDTO->get('value');
    
    // 2. 解析 JSON
    $model = json_decode($jsonModel);  // 'UserMap'
    $field = json_decode($jsonField);  // 'phone'
    $value = json_decode($jsonValue);  // '13800138000'
    
    // 3. 记录查询日志
    plog([
        'info' => '模糊查询映射表条件',
        '$model' => $model,
        '$field' => $field,
        '$value' => $value
    ], 'QueryMapFacadeService', 'GetShardInfoByNonBizId');
    
    // 4. 通过 modelMap 获取模型类并查询
    $data = ShardMapHelperFacade::getShardInfoByNonBizId(
        $this->run($model),  // 返回 UserMap::class
        $field,
        $value
    );
    
    // 5. 返回结果
    $result = [
        'code' => 0,
        'msg' => '查询成功',
        'data' => $data
    ];
    
    // 6. 记录结果日志
    plog([
        'info' => '模糊查询映射表结果',
        '$model' => $model,
        '$field' => $field,
        '$value' => $value,
        '$result' => $result
    ], 'QueryMapFacadeService', 'GetShardInfoByNonBizId');
    
    return $result;
}

getBizIdsByFuzzySearch 处理流程

public function getBizIdsByFuzzySearch(GetBizIdsDTO $getBizIdsDTO)
{
    // 1. 获取 DTO 参数
    $jsonModel = $getBizIdsDTO->get('model');
    $jsonField = $getBizIdsDTO->get('field');
    $jsonValue = $getBizIdsDTO->get('value');
    $jsonExtra = $getBizIdsDTO->get('extra');
    
    // 2. 解析 JSON
    $model = json_decode($jsonModel);  // 'UserMap'
    $field = json_decode($jsonField);  // 'phone'
    $value = json_decode($jsonValue);  // '138%'
    $extra = json_decode($jsonExtra, true);  // ['status' => 1]
    
    // 3. 记录查询日志
    plog([
        'info' => '模糊查询映射表条件',
        '$model' => $model,
        '$field' => $field,
        '$value' => $value,
        '$extra' => $extra
    ], 'QueryMapFacadeService', 'GetBizIdsByFuzzySearch');
    
    // 4. 通过 modelMap 获取模型类并查询
    $data = ShardMapHelperFacade::getBizIdsByFuzzySearch(
        $this->run($model),  // 返回 UserMap::class
        $field,
        $value,
        $extra
    );
    
    // 5. 返回结果
    $result = [
        'code' => 0,
        'msg' => '查询成功',
        'data' => $data
    ];
    
    // 6. 记录结果日志
    plog([
        'info' => '模糊查询映射表结果',
        '$model' => $model,
        '$field' => $field,
        '$value' => $value,
        '$extra' => $extra,
        '$result' => $result
    ], 'QueryMapFacadeService', 'GetBizIdsByFuzzySearch');
    
    return $result;
}

⚠️ 注意事项

1. 模型必须配置

使用前必须确保 $modelMap 中配置了对应的模型映射：

// ✅ 正确：UserMap 已配置
$getShardInfoDTO->set('model', json_encode('UserMap'));

// ❌ 错误：OrderMap 未配置会抛出异常
$getShardInfoDTO->set('model', json_encode('OrderMap'));
// 抛出异常: BaseModelEmptyError

2. JSON 字符串格式

DTO 的字段必须是 JSON 字符串：

// ✅ 正确：使用 json_encode
$getShardInfoDTO->set('model', json_encode('UserMap'));
$getShardInfoDTO->set('field', json_encode('phone'));
$getShardInfoDTO->set('value', json_encode('13800138000'));

// ❌ 错误：直接赋值字符串
$getShardInfoDTO->set('model', 'UserMap');  // 应该是 JSON 字符串

3. extra 参数类型

extra 参数是可选的，但如果有值必须是 JSON 字符串且能解析为数组：

// ✅ 正确：extra 为 JSON 数组字符串
$getBizIdsDTO->set('extra', json_encode(['status' => 1]));

// ✅ 正确：extra 为空
$getBizIdsDTO->set('extra', json_encode([]));
$getBizIdsDTO->set('extra', null);  // 或不设置

// ❌ 错误：extra 格式不正确
$getBizIdsDTO->set('extra', 'status=1');  // 应该是 JSON 字符串

4. 返回值检查

调用后必须检查返回值的 code 字段：

// ✅ 正确：检查返回值
$result = QueryMapFacade::getShardInfoByNonBizId($getShardInfoDTO);

if ($result['code'] !== 0) {
    // 处理错误
    return $this->error($result['msg']);
}

if (!$result['data']) {
    // 未找到数据
    return $this->error('数据不存在');
}

// 使用数据
$shardInfo = $result['data'];

🎯 最佳实践

1. 封装查询接口

建议为每个查询类型封装专门的接口：

class MapQueryController
{
    /**
     * 通过手机号查询用户分片信息
     */
    public function getUserByPhone(Request $request)
    {
        $phone = $request->input('phone');
        
        $getShardInfoDTO = new GetShardInfoDTO();
        $getShardInfoDTO->set('model', json_encode('UserMap'));
        $getShardInfoDTO->set('field', json_encode('phone'));
        $getShardInfoDTO->set('value', json_encode($phone));
        
        $result = QueryMapFacade::getShardInfoByNonBizId($getShardInfoDTO);
        
        return $this->success($result);
    }
    
    /**
     * 通过邮箱查询用户分片信息
     */
    public function getUserByEmail(Request $request)
    {
        $email = $request->input('email');
        
        $getShardInfoDTO = new GetShardInfoDTO();
        $getShardInfoDTO->set('model', json_encode('UserMap'));
        $getShardInfoDTO->set('field', json_encode('email'));
        $getShardInfoDTO->set('value', json_encode($email));
        
        $result = QueryMapFacade::getShardInfoByNonBizId($getShardInfoDTO);
        
        return $this->success($result);
    }
}

2. 统一异常处理

try {
    $result = QueryMapFacade::getShardInfoByNonBizId($getShardInfoDTO);
    
    if ($result['code'] !== 0) {
        throw new BusinessException($result['msg']);
    }
    
    return $this->success($result);
    
} catch (CommonException $e) {
    plog([
        'error' => $e->getMessage(),
        'model' => $getShardInfoDTO->get('model'),
    ], 'QueryMapFacade', 'queryError');
    
    return $this->error('查询失败');
}

3. 日志监控

定期检查查询日志：

# 查看查询日志
tail -f storage/logs/custom/QueryMapFacadeService/$(date +%Y-%m-%d)/GetShardInfoByNonBizId.log
tail -f storage/logs/custom/QueryMapFacadeService/$(date +%Y-%m-%d)/GetBizIdsByFuzzySearch.log

📊 与其他门面的关系

微服务API请求
    ↓
QueryMapFacade (映射表查询API)
    ↓
解析 DTO 参数
    ↓
modelMap (模型映射)
    ↓
ShardMapHelperFacade (查询映射表)
    ↓
返回查询结果

💬 总结

QueryMapFacade 是游鹄生态中微服务间映射表查询的API入口，其核心价值在于：

  1. ✅ 统一API接口：提供统一的映射表查询API
  2. ✅ 模型映射管理：通过 modelMap 管理不同模型的查询
  3. ✅ DTO参数封装：使用DTO对象封装请求参数，类型安全
  4. ✅ 非业务ID查询：支持通过手机号、邮箱等非业务ID查询
  5. ✅ 模糊查询支持：支持模糊查询获取业务ID列表
  6. ✅ 日志追踪：完整的查询操作日志记录

在实际开发中，建议为每个查询场景封装专门的API接口，以获得更好的代码组织和可维护性。

© 2026 youhujun & xueer. All rights reserved.

游鹄君的博客
Copyright © 2026 游鹄君