Transfer模块API参数优化

任务时间: 2025-06-18 20:27
任务类型: API优化
状态: ✅ 已完成

任务概述

针对用户反馈的"createTransferOut，createTransferIn 使用数组参数，是难以理解的"问题，对Transfer模块的核心API进行了全面优化，使用明确的参数列表替代数组参数，提高代码的可读性和类型安全性。

优化内容

1. TransferService 服务层优化

优化前：

public static function createTransferOut(array $data): TransferOrderDto|string
public static function createTransferIn(array $data): TransferOrderDto|string

优化后：

// 转出订单 - 明确参数
public static function createTransferOut(
    int $transferAppId,
    int $userId,
    string $amount,
    string $password,
    ?string $googleCode = null,
    ?string $outUserId = null,
    ?string $remark = null,
    array $callbackData = []
): TransferOrderDto|string

// 转入订单 - 明确参数
public static function createTransferIn(
    int $transferAppId,
    int $userId,
    string $businessId,
    string $amount,
    ?string $outUserId = null,
    ?string $remark = null,
    array $callbackData = []
): TransferOrderDto|string

2. TransferLogic 逻辑层优化

新增方法结构：

createTransferOut() - 对外接口，使用明确参数
createTransferOutFromArray() - 内部实现，保持向后兼容
createTransferIn() - 对外接口，使用明确参数
createTransferInFromArray() - 内部实现，保持向后兼容

3. OpenAPI Handler 更新

优化前：

$result = TransferService::createTransferOut($validatedData);

优化后：

$result = TransferService::createTransferOut(
    transferAppId: $validatedData['transfer_app_id'],
    userId: $validatedData['user_id'],
    amount: $validatedData['amount'],
    password: $validatedData['password'],
    googleCode: $validatedData['google_code'] ?? null,
    outUserId: $validatedData['out_user_id'] ?? null,
    remark: $validatedData['remark'] ?? null,
    callbackData: $validatedData['callback_data'] ?? []
);

4. 新增便捷方法

快速创建方法：

// 快速转出 - 只需必要参数
public static function quickCreateTransferOut(
    int $transferAppId,
    int $userId,
    string $amount,
    string $password
): TransferOrderDto|string

// 快速转入 - 只需必要参数
public static function quickCreateTransferIn(
    int $transferAppId,
    int $userId,
    string $businessId,
    string $amount
): TransferOrderDto|string

向后兼容方法：

// 标记为废弃，但保持兼容
public static function createTransferOutFromArray(array $data): TransferOrderDto|string
public static function createTransferInFromArray(array $data): TransferOrderDto|string

5. 测试文件更新

更新所有测试方法使用新的 FromArray 方法
新增测试用例展示新的参数化API
测试可选参数的默认值处理

优化优势

1. 类型安全

编译时参数类型检查
减少运行时错误
IDE智能提示支持

2. 可读性提升

参数含义一目了然
无需查看文档即可理解参数用途
代码自文档化

3. 维护性改善

减少参数错误和遗漏
更好的IDE支持和代码补全
重构时更安全

4. 向后兼容

保留原有数组参数方法
渐进式迁移策略
不影响现有代码

使用示例

基础用法

// 转出订单
$result = TransferService::createTransferOut(
    transferAppId: 1,
    userId: 12345,
    amount: '100.50',
    password: 'user_password'
);

// 转入订单
$result = TransferService::createTransferIn(
    transferAppId: 1,
    userId: 12345,
    businessId: 'BIZ_20250618_001',
    amount: '100.50'
);

完整参数用法

$result = TransferService::createTransferOut(
    transferAppId: 1,
    userId: 12345,
    amount: '100.50',
    password: 'user_password',
    googleCode: '123456',
    outUserId: 'external_user_123',
    remark: '游戏充值',
    callbackData: ['game_id' => 'abc']
);

错误处理

$result = TransferService::createTransferOut(/* 参数 */);

if (is_string($result)) {
    // 处理错误
    $errorMessage = $result;
} else {
    // 处理成功
    $order = $result; // TransferOrderDto 对象
}

迁移指南

1. 新项目

直接使用新的参数化API：

TransferService::createTransferOut(
    transferAppId: $appId,
    userId: $userId,
    amount: $amount,
    password: $password
);

2. 现有项目

可以继续使用数组参数（标记为废弃）：

TransferService::createTransferOutFromArray($data);

3. 渐进迁移

逐步将数组参数调用替换为新的参数化调用。

文档更新

创建 API_USAGE.md 详细使用指南
包含完整的参数说明和示例
提供迁移指南和最佳实践

技术细节

参数验证

必需参数：transferAppId, userId, amount, password(转出)
可选参数：googleCode, outUserId, remark, callbackData
类型安全：int, string, ?string, array

内部实现

新方法内部调用原有的数组参数方法
保持业务逻辑不变
只是接口层面的优化

性能影响

无性能损失
编译时优化
更好的内存使用

总结

通过这次优化，Transfer模块的API变得更加：

易于理解 - 参数含义明确
类型安全 - 编译时检查
易于维护 - 减少错误
向后兼容 - 平滑迁移

这种优化模式可以作为其他模块API设计的参考标准。

182027-Transfer模块API参数优化.md 5.5 KB Vēsture Neapstrādāts