kknongchang_2506/app/Module/Transfer/Docs/API_USAGE.md

Transfer模块API使用指南

概述

Transfer模块提供了明确的参数接口，替代了原来难以理解的数组参数方式。新的API更加类型安全，易于理解和维护。

创建转出订单

完整参数版本

use App\Module\Transfer\Services\TransferService;

// 创建转出订单 - 完整参数
$result = TransferService::createTransferOut(
    transferAppId: 1,                    // 划转应用ID
    userId: 12345,                       // 用户ID
    amount: '100.50',                    // 转出金额
    password: 'user_password',           // 安全密码
    googleCode: '123456',                // 谷歌验证码（可选）
    outUserId: 'external_user_123',      // 外部用户ID（可选）
    remark: '游戏充值',                   // 备注（可选）
    callbackData: ['game_id' => 'abc']   // 回调数据（可选）
);

if (is_string($result)) {
    // 处理错误
    echo "创建失败: " . $result;
} else {
    // 成功，$result 是 TransferOrderDto 对象
    echo "订单创建成功，ID: " . $result->id;
}

简化版本

// 快速创建转出订单 - 只需必要参数
$result = TransferService::quickCreateTransferOut(
    transferAppId: 1,
    userId: 12345,
    amount: '100.50',
    password: 'user_password'
);

创建转入订单

完整参数版本

// 创建转入订单 - 完整参数
$result = TransferService::createTransferIn(
    transferAppId: 1,                    // 划转应用ID
    userId: 12345,                       // 用户ID
    businessId: 'BIZ_20250618_001',      // 业务订单ID
    amount: '100.50',                    // 转入金额
    outUserId: 'external_user_123',      // 外部用户ID（可选）
    remark: '游戏提现',                   // 备注（可选）
    callbackData: ['game_id' => 'abc']   // 回调数据（可选）
);

简化版本

// 快速创建转入订单 - 只需必要参数
$result = TransferService::quickCreateTransferIn(
    transferAppId: 1,
    userId: 12345,
    businessId: 'BIZ_20250618_001',
    amount: '100.50'
);

向后兼容

如果您的代码仍在使用数组参数，可以使用向后兼容方法：

// 向后兼容 - 转出订单
$data = [
    'transfer_app_id' => 1,
    'user_id' => 12345,
    'amount' => '100.50',
    'password' => 'user_password',
    'google_code' => '123456',
    'out_user_id' => 'external_user_123',
    'remark' => '游戏充值',
    'callback_data' => ['game_id' => 'abc']
];

$result = TransferService::createTransferOutFromArray($data);

// 向后兼容 - 转入订单
$data = [
    'transfer_app_id' => 1,
    'user_id' => 12345,
    'business_id' => 'BIZ_20250618_001',
    'amount' => '100.50',
    'out_user_id' => 'external_user_123',
    'remark' => '游戏提现',
    'callback_data' => ['game_id' => 'abc']
];

$result = TransferService::createTransferInFromArray($data);

参数说明

转出订单参数

参数名	类型	必填	说明
transferAppId	int	是	划转应用ID
userId	int	是	用户ID
amount	string	是	转出金额（字符串格式，支持小数）
password	string	是	用户安全密码
googleCode	string|null	否	谷歌验证码（6位数字）
outUserId	string|null	否	外部用户ID
remark	string|null	否	备注信息
callbackData	array	否	回调数据（键值对数组）

转入订单参数

参数名	类型	必填	说明
transferAppId	int	是	划转应用ID
userId	int	是	用户ID
businessId	string	是	业务订单ID（外部系统的订单标识）
amount	string	是	转入金额（字符串格式，支持小数）
outUserId	string|null	否	外部用户ID
remark	string|null	否	备注信息
callbackData	array	否	回调数据（键值对数组）

返回值处理

所有创建方法都返回 TransferOrderDto|string：

• 成功时返回 TransferOrderDto 对象

• 失败时返回错误信息字符串

  $result = TransferService::createTransferOut(/* 参数 */);
  
  if (is_string($result)) {
  // 处理错误
  $errorMessage = $result;
  // 记录日志、返回错误响应等
  } else {
  // 处理成功
  $order = $result; // TransferOrderDto 对象
  $orderId = $order->id;
  $status = $order->status;
  $amount = $order->amount;
  // 其他业务逻辑
  }
  

最佳实践

1. 使用命名参数：PHP 8.0+ 支持命名参数，提高代码可读性
2. 类型检查：利用返回值类型检查处理成功和失败情况
3. 错误处理：始终检查返回值类型，妥善处理错误情况
4. 参数验证：在调用API前进行基础参数验证
5. 日志记录：记录重要的操作和错误信息

迁移指南

从数组参数迁移

旧代码：

$data = [
    'transfer_app_id' => 1,
    'user_id' => 12345,
    'amount' => '100.50',
    'password' => 'password'
];
$result = TransferService::createTransferOut($data);

新代码：

$result = TransferService::createTransferOut(
    transferAppId: 1,
    userId: 12345,
    amount: '100.50',
    password: 'password'
);

优势

1. 类型安全：编译时检查参数类型
2. IDE支持：更好的代码补全和提示
3. 可读性：参数含义一目了然
4. 维护性：减少参数错误和遗漏
5. 文档化：参数名称即文档

注意事项

1. 金额参数使用字符串类型，避免浮点数精度问题
2. 可选参数使用 null 作为默认值
3. 回调数据必须是关联数组格式
4. 业务订单ID必须在同一应用内唯一
5. 密码和验证码等敏感信息需要妥善处理