LikeShop 原生系统对手机号、地址等字段的展示控制是分散且不彻底的。ThinkPHP 的中间件只能处理请求输入,无法拦截模型序列化、导出或日志输出;一旦执行 return json($user) 或 $user->toArray(),原始字段会直接吐出,中间件早已执行完毕。这意味着“全系列商城”的脱敏不能靠改某一个 Controller 或加一个中间件来解决,需要一套配置驱动 + 分层执行的运维体系。
一、脱敏的“分层”逻辑:不同链路,不同手段
敏感数据在系统中会流经多条链路,每条链路的脱敏方式不同:
| 链路 | 典型场景 | 有效脱敏手段 | 无效/危险手段 |
|---|---|---|---|
| API 输出 | 用户中心、订单列表、后台管理 | 模型访问器(PHP)/ DTO 序列化拦截(Java) | 中间件、Controller 手动处理 |
| 数据导出 | 后台导出 CSV/Excel | 导出逻辑内嵌脱敏函数 | 依赖模型访问器(cursor() 可能绕过) |
| 日志记录 | 请求日志、审计日志、异常日志 | 写日志前预处理 | 事后过滤 |
| 数据库落盘 | 手机号、地址存储 | 字段级加密(AES-256) | 仅靠应用层脱敏 |
核心原则:脱敏必须在数据离开业务逻辑边界的每一个出口生效,而不是指望某一个“万能中间件”。
二、统一配置层:定义“谁、在哪、看到什么”
在 app/common/ 下新增一个配置读取入口,所有脱敏逻辑从这里获取策略,不在代码中硬编码掩码规则。
2.1 配置表设计
CREATE TABLE `ls_mask_policy` (
`id` int UNSIGNED NOT NULL AUTO_INCREMENT,
`scene` varchar(50) NOT NULL COMMENT '场景:api_user_center / admin_order_list / export_csv',
`field_key` varchar(50) NOT NULL COMMENT '字段标识:mobile / address / real_name',
`role_scope` varchar(100) NOT NULL DEFAULT 'all' COMMENT '生效角色:all / platform / merchant / user',
`mask_type` varchar(20) NOT NULL DEFAULT 'partial' COMMENT 'partial / full / hash / none',
`mask_rule` varchar(100) DEFAULT '3-4' COMMENT '保留前3位后4位(partial时生效)',
`is_enable` tinyint DEFAULT '1',
PRIMARY KEY (`id`),
UNIQUE KEY `uk_scene_field_role` (`scene`, `field_key`, `role_scope`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
role_scope 是关键。同一个 mobile 字段,平台运营在后台看到明文(便于客服回拨),商户只能看到脱敏后的(防止商户之间串数据),C 端用户看到的是自己的明文、他人的脱敏值。配置驱动让这套规则可以通过后台调整,而不是改代码发版。
2.2 统一的脱敏函数
class MaskHelper
{
public static function apply($value, $fieldKey, $scene, $role): string
{
if (empty($value) || !is_string($value)) return (string)$value;
$policy = MaskPolicyModel::where('scene', $scene)
->where('field_key', $fieldKey)
->whereIn('role_scope', ['all', $role])
->where('is_enable', 1)
->order('role_scope', 'desc') // 特定角色优先于 all
->find();
if (!$policy || $policy['mask_type'] === 'none') return $value;
if ($policy['mask_type'] === 'full') return '****';
// partial:按 mask_rule 中的 “保留前N-后M” 执行
[$keepStart, $keepEnd] = explode('-', $policy['mask_rule'] ?? '3-4');
$keepStart = (int)$keepStart; $keepEnd = (int)$keepEnd;
$len = mb_strlen($value);
if ($len <= $keepStart + $keepEnd) {
return mb_substr($value, 0, 1) . str_repeat('*', $len - 1);
}
return mb_substr($value, 0, $keepStart)
. str_repeat('*', $len - $keepStart - $keepEnd)
. mb_substr($value, -$keepEnd);
}
}
手机号 13812345678 按 3-4 规则得到 138****5678。地址按 6-4 规则得到 广东省深圳****区XX号。规则可配,不同字段用不同的保留策略。
三、PHP 版:模型访问器是唯一可靠的 API 出口
ThinkPHP 中,get{Field}Attr 访问器是唯一能覆盖 toArray()、toJson()、模板渲染、$model->field 直接访问等所有读取场景的机制。中间件拦不住这些路径。
3.1 在用户模型上定义访问器
class User extends BaseModel
{
public function getMobileAttr($value)
{
if (empty($value) || !is_string($value)) return $value;
return MaskHelper::apply($value, 'mobile', 'api_user_center', $this->getRole());
}
public function getRealNameAttr($value)
{
if (empty($value)) return $value;
return MaskHelper::apply($value, 'real_name', 'api_user_center', $this->getRole());
}
}
注意两个边界:
第一,关联模型不会继承主模型的访问器。如果 Order 模型通过 with('user') 关联了 User,User 自身的访问器会生效,但如果 Order 模型自己也有 contact_mobile 字段(订单快照),必须在 Order 模型上单独定义 getContactMobileAttr。
第二,地址是组合字段。ls_user_address 中的 province、city、district、address 是分开存储的。脱敏应该在拼接后的展示层做,而不是逐字段掩码导致地址结构错乱。可以在 UserAddress 模型上增加一个 getFullAddressMaskedAttr 虚拟属性,拼接后按配置掩码。
3.2 原生查询的绕过风险
Db::table('user')->select() 完全不经过模型,访问器失效。二开或维护时必须禁止在需要脱敏的出口使用原生查询,或者强制在查询后手动调用 MaskHelper。这一点应该在代码规范中明确,并在 Code Review 中检查。
四、Java 版:拦截器 + 注解的出口控制
Java 版没有 ThinkPHP 的访问器机制,脱敏放在响应序列化层。Spring Boot 中可以通过 ResponseBodyAdvice 在 Controller 返回数据后、JSON 序列化前进行拦截。
4.1 注解标记敏感字段
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Sensitive {
String scene();
String field();
}
在 DTO 字段上标注:
public class UserVO {
private String nickname;
@Sensitive(scene = "admin_user_list", field = "mobile")
private String mobile;
@Sensitive(scene = "admin_order_list", field = "address")
private String fullAddress;
}
4.2 ResponseBodyAdvice 拦截
@RestControllerAdvice
public class MaskResponseAdvice implements ResponseBodyAdvice<Object> {
@Override
public Object beforeBodyWrite(Object body, MethodParameter returnType,
MediaType selectedContentType,
Class<? extends HttpMessageConverter<?>> converterType,
ServerHttpRequest request, ServerHttpResponse response) {
if (body == null) return null;
String role = resolveCurrentRole(); // 从 Sa-Token 会话解析,不信任前端
maskRecursively(body, role);
return body;
}
private void maskRecursively(Object obj, String role) {
if (obj instanceof Collection) {
((Collection<?>) obj).forEach(item -> maskRecursively(item, role));
} else if (obj != null && obj.getClass().getName().startsWith("com.xxx.vo")) {
for (Field field : obj.getClass().getDeclaredFields()) {
Sensitive s = field.getAnnotation(Sensitive.class);
if (s != null) {
field.setAccessible(true);
Object val = field.get(obj);
if (val instanceof String) {
field.set(obj, MaskHelper.apply((String) val, s.field(), s.scene(), role));
}
}
}
}
}
}
Java 版的安全加固强调权限校验必须在服务端强制执行,脱敏同理——role 从 Sa-Token 会话解析,不从前端参数读取。
五、日志与导出:两条最容易泄露的旁路
5.1 日志脱敏
“接口返回看起来已脱敏,但日志里却出现明文手机号”是脱敏实施中最常见的疏漏。ThinkPHP 的 Log::write($request->param()) 记录的是原始快照,访问器和中间件都管不到这里。
方案是在日志写入入口统一预处理:
class SafeLogger
{
public static function write(string $level, string $message, array $context = []): void
{
$context = self::maskContext($context);
Log::write($level, $message . ' ' . json_encode($context, JSON_UNESCAPED_UNICODE));
}
private static function maskContext(array $data): array
{
$sensitiveKeys = ['mobile', 'phone', 'contact', 'telephone', 'address', 'id_card'];
array_walk_recursive($data, function (&$value, $key) use ($sensitiveKeys) {
if (in_array(strtolower($key), $sensitiveKeys) && is_string($value)) {
$value = MaskHelper::apply($value, $key, 'log', 'all');
}
});
return $data;
}
}
日志脱敏必须在写入前完成,而不是事后扫描日志文件。加密日志文件解决的是存储安全,不解决日志中本来就有明文的问题。
5.2 导出脱敏
导出走 cursor() 流式查询时,如果直接取字段值,可能绕过模型访问器(取决于具体查询方式)。导出逻辑中必须显式调用脱敏函数,按导出场景的配置执行:
foreach ($query->cursor() as $row) {
$row['mobile'] = MaskHelper::apply($row['mobile'], 'mobile', 'export_csv', $currentRole);
fputcsv($fp, $row);
}
导出场景的 role_scope 通常设为 all,即无论谁导出,手机号都必须掩码。如果业务确实需要导出明文(例如客服批量回访),应走独立的“明文导出”权限节点,并配合加密 ZIP + 密码分发,而不是在通用导出中放开。
六、多商户与 SaaS 版:tenant_id 是脱敏的前置条件
多商户和 SaaS 版的脱敏有一个单商户版不存在的约束:如果 tenant_id 隔离失效,脱敏做得再好也没有意义。商户 B 能查到商户 A 的用户记录,即使手机号打了码,地址、订单金额、消费频次仍然是泄露。
LikeShop 多商户 Java 版使用 MyBatis-Plus 的 TenantLineInnerInterceptor 自动注入 tenant_id,但任何绕开 MyBatis-Plus 的原生 SQL 都必须显式带上 tenant_id 过滤。在脱敏配置中,scene 的设计应该与租户上下文绑定——例如 admin_order_list 的查询首先被 tenant_id 限制在商户自己的数据范围内,然后脱敏才是在这个范围之上的“再收窄”。
SaaS 版的租户识别必须在请求生命周期最早执行,否则模型事件、日志记录、缓存写入可能已经基于错误的租户上下文完成,脱敏策略也会应用到错误的角色上。
七、运维配置与验证清单
脱敏不是一次性开发,而是持续运维。上线前逐项核对:
配置层:ls_mask_policy 中是否覆盖了 mobile、address、real_name 三个核心字段的 api、export、log 三个场景;每个场景的 role_scope 是否与实际的权限分层对齐。
PHP 出口:用 Postman 直接请求用户信息、订单列表、地址详情接口,确认返回的手机号和地址已脱敏;用 Db::table('user')->select() 做一次对照测试,确认没有遗漏的原生查询出口。
Java 出口:检查 @Sensitive 注解是否覆盖了所有返回用户数据的 VO;用商户账号和平台账号分别请求同一接口,确认返回的脱敏级别符合 role_scope 配置。
日志:在测试环境触发一次下单,查看 runtime/log/ 中的请求日志,确认 mobile、address 字段不是明文。
导出:导出用户列表 CSV,打开确认手机号列已掩码。
多商户隔离:用商户 B 的账号尝试通过参数篡改查询商户 A 的用户数据,确认被 tenant_id 过滤拦截,而不是靠脱敏“遮住”。
八、总结
LikeShop 全系列商城的敏感数据脱敏,核心是三条线:
配置驱动,而非硬编码:ls_mask_policy 定义“场景 × 字段 × 角色”的脱敏规则,掩码位数可调,后台可改,不发版。
出口覆盖,而非入口拦截:PHP 版用模型访问器覆盖 API 和序列化出口,Java 版用 ResponseBodyAdvice 拦截 DTO 序列化;日志和导出作为两条独立旁路,在写入前显式脱敏。中间件只能处理输入,不能作为输出脱敏的手段。
隔离是脱敏的前提:多商户和 SaaS 版必须先保证 tenant_id 隔离生效,脱敏是在正确数据范围之上的二次收窄。没有隔离的脱敏,只是一层可以被绕过的遮罩。
守住三条底线:不在中间件里做输出脱敏、日志写入前必须过滤、tenant_id 隔离先于脱敏生效。这样一套配置可以同时服务于 LikeShop 单商户、多商户、SaaS 各版本,而不需要为每个产品线重复实现脱敏逻辑。