ShardMapHelperFacade 使用手册

概述

ShardMapHelperFacade 是专门为分库分表映射库表设计的门面服务，继承自 ShardHelperFacade 的所有功能，并新增了映射表特有的查询方法。

特点：

• ✅ 继承 ShardHelperFacade 所有方法
• ✅ 专门用于映射表（Map表）操作
• ✅ 新增非业务ID查询功能
• ✅ 新增模糊查询功能
• ✅ 内置 Redis Hash 缓存

适用场景： 用户映射表（UserMap）、订单映射表（OrderMap）等映射库表

---

核心方法

继承方法

ShardMapHelperFacade 继承了 ShardHelperFacade 的所有方法：

• getShardInfo() - 获取分片信息
• getTableName() - 获取分表名
• getDbName() - 获取分库名
• withShardContext() - 带分片上下文执行闭包
• createWithShard() - 带分片创建模型
• queryAllShards() - 全表遍历查询
• queryByShardWithCache() - 带缓存的精准查询
• clearCache() - 清理缓存
• registerCacheInvalidation() - 注册缓存自动失效

详细使用方法请参考 ShardHelperFacade 使用手册

---

新增方法

1. 通过非业务ID查询分片信息

getShardInfoByNonBizId(string $mapModelClass, string $searchField, mixed $searchValue): ?array

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

适用场景： 通过账号名、手机号、订单号等非业务ID字段查询数据所在的分片。

参数：

• $mapModelClass - 映射表模型类（如 UserMap::class、OrderMap::class）
• $searchField - 查询字段（如 account_name、phone、order_no）
• $searchValue - 查询值（如 develop、13800138000、ORD20260304001）

返回值：

[
    'db' => 'dssp_0',          // 主表分库名
    'table' => 'users_0',       // 主表分表名
    'shard_key' => 0,          // 分片键
    'base_table' => 'users',    // 主表基础表名
    'biz_id' => '276406781286953' // 业务ID
]

未找到返回： null

示例 1：通过账号名查询用户分片信息

use App\Facades\Common\V1\Shard\Map\ShardMapHelperFacade;
use App\Models\LaravelShardMap\V1\Map\UserMap;

$shardInfo = ShardMapHelperFacade::getShardInfoByNonBizId(
    UserMap::class,
    'account_name',
    'develop'
);

if ($shardInfo) {
    p("用户 {$shardInfo['biz_id']} 在 {$shardInfo['db']}.{$shardInfo['table']}");

    // 现在可以根据分片信息查询主表
    $user = User::queryByShard($shardInfo['biz_id'])->first();
}

示例 2：通过手机号查询

$shardInfo = ShardMapHelperFacade::getShardInfoByNonBizId(
    UserMap::class,
    'phone',
    '13800138000'
);

// 通过订单号查询
$orderInfo = ShardMapHelperFacade::getShardInfoByNonBizId(
    OrderMap::class,
    'order_no',
    'ORD20260304001'
);

---

2. 模糊查询获取业务ID列表

getBizIdsByFuzzySearch(string $mapModelClass, string $searchField, mixed $searchValue, array $extraConditions = []): array

通过模糊查询获取符合条件的业务ID列表。

适用场景： 搜索功能、自动补全、模糊匹配等场景。

参数：

• $mapModelClass - 映射表模型类
• $searchField - 模糊查询字段（如 nick_name、phone）
• $searchValue - 模糊查询值（支持 % 占位符）
• $extraConditions - 额外精准条件（可选，如 ['status' => 1]）

返回值： 业务ID数组（去重、非空）

示例 1：搜索账号名包含 'dev' 的用户

use App\Facades\Common\V1\Shard\Map\ShardMapHelperFacade;
use App\Models\LaravelShardMap\V1\Map\UserMap;

$userUids = ShardMapHelperFacade::getBizIdsByFuzzySearch(
    UserMap::class,
    'account_name',
    '%dev%'  // 查询包含 'dev' 的账号名
);

p('找到的用户:', count($userUids));

// 遍历查询用户信息
foreach ($userUids as $userUid) {
    $user = User::queryByShard($userUid)->first();
    p("用户: {$user->account_name}");
}

示例 2：搜索手机号以 '138' 开头的用户

$userUids = ShardMapHelperFacade::getBizIdsByFuzzySearch(
    UserMap::class,
    'phone',
    '138%'  // 查询手机号以 '138' 开头的用户
);

示例 3：带额外条件的搜索

$userUids = ShardMapHelperFacade::getBizIdsByFuzzySearch(
    UserMap::class,
    'nick_name',
    '%游鹄%',
    ['account_status' => 1]  // 额外条件：账号状态为1
);

示例 4：搜索订单号

$orderUids = ShardMapHelperFacade::getBizIdsByFuzzySearch(
    OrderMap::class,
    'order_no',
    'ORD202603%'
);

---

完整示例

示例 1：用户登录流程

use App\Facades\Common\V1\Shard\Map\ShardMapHelperFacade;
use App\Models\LaravelShardMap\V1\Map\UserMap;
use App\Models\LaravelFastApi\V1\User\User;

public function login(Request $request)
{
    $accountName = $request->input('account_name');

    // 1. 通过账号名查询用户分片信息
    $shardInfo = ShardMapHelperFacade::getShardInfoByNonBizId(
        UserMap::class,
        'account_name',
        $accountName
    );

    if (!$shardInfo) {
        throw new CommonException('UserNotFoundError');
    }

    // 2. 根据分片信息查询用户
    $user = User::queryByShard($shardInfo['biz_id'])->first();

    // 3. 验证密码并登录
    // ...
}

---

示例 2：用户搜索功能

use App\Facades\Common\V1\Shard\Map\ShardMapHelperFacade;
use App\Models\LaravelShardMap\V1\Map\UserMap;
use App\Models\LaravelFastApi\V1\User\User;

public function searchUser(Request $request)
{
    $keyword = $request->input('keyword', '');

    if (empty($keyword)) {
        return collect();
    }

    // 1. 通过账号名模糊搜索
    $userUids = ShardMapHelperFacade::getBizIdsByFuzzySearch(
        UserMap::class,
        'account_name',
        "%{$keyword}%",  // 支持模糊匹配
        ['account_status' => 1]  // 只查询状态正常的用户
    );

    // 2. 批量查询用户信息
    $users = collect();
    foreach ($userUids as $userUid) {
        $user = User::queryByShard($userUid)->first();
        if ($user) {
            $users->push($user);
        }
    }

    return $users;
}

---

示例 3：创建用户并同步到映射表

use App\Facades\Common\V1\Shard\Map\ShardMapHelperFacade;
use App\Models\LaravelFastApi\V1\User\User;
use App\Models\LaravelShardMap\V1\Map\UserMap;

public function register(Request $request)
{
    $accountName = $request->input('account_name');
    $password = $request->input('password');

    // 1. 创建用户（使用 ShardHelperFacade）
    $userUid = generateSnowflakeId();
    $user = ShardHelperFacade::createWithShard(User::class, $userUid, [
        'user_uid' => $userUid,
        'account_name' => $accountName,
        'password' => bcrypt($password),
        'account_status' => 1,
    ]);

    // 2. 计算分片信息
    $shardInfo = ShardHelperFacade::getShardInfo(User::class, $userUid);

    // 3. 创建映射表记录（使用 ShardMapHelperFacade）
    ShardMapHelperFacade::createWithShard(UserMap::class, $userUid, [
        'user_uid' => $userUid,
        'account_name' => $accountName,
        'shard_db' => $shardInfo['db'],
        'shard_table' => $shardInfo['table'],
    ]);

    return $user;
}

---

示例 4：根据手机号查询用户

use App\Facades\Common\V1\Shard\Map\ShardMapHelperFacade;
use App\Models\LaravelShardMap\V1\Map\UserMap;
use App\Models\LaravelFastApi\V1\User\User;

public function getUserByPhone(string $phone)
{
    // 1. 通过手机号查询分片信息
    $shardInfo = ShardMapHelperFacade::getShardInfoByNonBizId(
        UserMap::class,
        'phone',
        $phone
    );

    if (!$shardInfo) {
        throw new CommonException('UserNotFoundError');
    }

    // 2. 查询用户
    $user = User::queryByShard($shardInfo['biz_id'])->first();

    return $user;
}

---

配置说明

ShardMapHelperFacade 使用 shard_map 配置：

环境变量

# 映射表分片配置
SHARD_MAP_SHARD_DB_PREFIX=dssp_
SHARD_MAP_SHARD_DB_COUNT=4
SHARD_MAP_SHARD_TABLE_COUNT=10

# 缓存配置
SHARD_MAP_SHARD_CACHE_ENABLE=true
SHARD_MAP_SHARD_CACHE_DB=3
SHARD_MAP_SHARD_CACHE_PREFIX=shard_
SHARD_MAP_SHARD_CACHE_TTL=3600

配置文件

// config/custom/laravel-shard-map/shard_map.php

return [
    'db_prefix' => env('SHARD_MAP_SHARD_DB_PREFIX', 'dssp_'),
    'db_connection' => env('SHARD_MAP_SHARD_DB_CONNECTION', 'laravel_shard_map'),
    'shard' => [
        'db_count' => env('SHARD_MAP_SHARD_DB_COUNT', 4),
        'table_count' => env('SHARD_MAP_SHARD_TABLE_COUNT', 10),
        'default_db' => env('SHARD_MAP_SHARD_DEFAULT_DB', 'dssp_0'),
        'cache' => [
            'enable' => env('SHARD_MAP_SHARD_CACHE_ENABLE', true),
            'db' => env('SHARD_MAP_SHARD_CACHE_DB', 3),
            'prefix' => env('SHARD_MAP_SHARD_CACHE_PREFIX', 'shard_'),
            'ttl' => env('SHARD_MAP_SHARD_CACHE_TTL', 3600),
            'allow_models' => [],  // 空数组表示允许所有模型缓存
            'model_ttl' => [
                // 可以为特定模型设置不同的过期时间
            ],
        ],
    ],
];

---

最佳实践

1. 使用 getShardInfoByNonBizId 代替直接查询

不推荐：

// 直接查询映射表
$userMap = UserMap::where('account_name', 'develop')->first();
if ($userMap) {
    $user = User::queryByShard($userMap->user_uid)->first();
}

推荐：

// 使用门面方法（带缓存）
$shardInfo = ShardMapHelperFacade::getShardInfoByNonBizId(
    UserMap::class,
    'account_name',
    'develop'
);
if ($shardInfo) {
    $user = User::queryByShard($shardInfo['biz_id'])->first();
}

---

2. 模糊查询时使用提前退出

$userUids = ShardMapHelperFacade::getBizIdsByFuzzySearch(
    UserMap::class,
    'account_name',
    '%dev%',
    ['account_status' => 1]  // 额外条件减少结果集
);

---

3. 缓存自动失效注册

// app/Providers/AppServiceProvider.php

use App\Facades\Common\V1\Shard\Map\ShardMapHelperFacade;
use App\Models\LaravelShardMap\V1\Map\UserMap;

public function boot()
{
    // 注册映射表缓存自动失效
    ShardMapHelperFacade::registerCacheInvalidation(UserMap::class);
}

---

注意事项

1. 专门用于映射表：ShardMapHelperFacade 专门为映射表（UserMap、OrderMap等）设计，主表请使用 ShardHelperFacade。

2. 非业务ID查询：getShardInfoByNonBizId 只能查询映射表，用于定位主表的分片信息。

3. 缓存机制：所有查询都内置 Redis 缓存，提升性能。

4. 模糊查询占位符：使用 % 作为通配符，如 %dev%、138%。

5. 日志记录：所有分片操作都会记录日志到 storage/logs/custom/shard/ 目录，方便调试。

---

与 ShardHelperFacade 的区别

特性	ShardHelperFacade	ShardMapHelperFacade
用途	主表分库分表操作	映射表分库分表操作
配置	youhujun/youhu/youhushop	shard_map
继承	原生方法	继承 ShardHelperFacade
新增方法	无	getShardInfoByNonBizId()、getBizIdsByFuzzySearch()
查询场景	已知业务ID查询	非业务ID查询、模糊查询

---

作者： 游鹄君 & 雪儿
更新日期： 2026-03-05