README

适用于 PHP 的 MIoT API 客户端库，支持自动处理 token 获取、签名生成和异常处理。

目录结构

src/
├── Auth/             # 权限验证相关类
│   ├── TokenManager.php         # Token 获取和管理
│   └── SignatureGenerator.php   # 签名生成器
├── Exception/        # 异常类
│   ├── MiotApiException.php     # 基础异常类
│   ├── TokenException.php       # Token 相关异常
│   ├── SignatureException.php   # 签名相关异常
│   ├── HttpException.php        # HTTP 相关异常
│   └── ApiException.php         # API 业务异常
├── Platform/         # 业务逻辑相关类
│   └── Device.php               # 设备相关业务
└── Client.php        # 客户端主类

安装

composer require mychway/miot-api-client

使用方法

初始化客户端

use Mychway\MiotApi\Client;

/* 商户后台获取token */ 
$token = Client::getToken('your_app_key', 'your_app_secret', [
                'base_url' => 'https://test-sz-api.4bty.cn',
                'verify' => false
            ]);
            
/* 开发者中心获取token */ 
$token = Client::getToken($info['app_id'], $info['app_secret'], [
                'token_type' => 2,
                'base_url' => $info['api_url'],
                'verify' => false
            ]);

$client = new Client('your_app_key', 'your_app_secret', [
    'base_url' => 'https://test-sz-api.4bty.cn', // 必填
    'token' => $token,
    'verify' => false, // 可选，是否验证 SSL 证书，默认 false
]);

$data = $client->get('/v1/device/list', [
                'product_key' => ''
            ]);

获取设备服务

$deviceService = $client->device();

直接调用 HTTP 方法

客户端提供了便捷的 HTTP 方法，可以直接调用 API 接口。

GET 请求

// 发送 GET 请求
$response = $client->get('/v1/device/list', [
    'page' => 1,
    'page_size' => 10,
]);
print_r($response);

POST 表单请求

// 发送 POST 表单请求
$response = $client->post('/v1/device/create', [
    'device_name' => '测试设备',
    'product_key' => '123456',
]);
print_r($response);

POST JSON 请求

// 发送 POST JSON 请求
$response = $client->postJson('/v1/device/update', [
    'device_id' => 'abc123',
    'params' => [
        'name' => '更新设备名称',
        'status' => 1
    ]
]);
print_r($response);

调用设备列表接口

use Mychway\MiotApi\Exception\ApiException;

try {
    $params = [
        'page' => 1,
        'page_size' => 10,
        'device_name' => '测试', // 可选，设备名称模糊查询
        'product_keys' => 'key1,key2', // 可选，多个产品key逗号分隔
        'sort_name' => 'create_time', // 可选，排序字段
        'sort_order' => 'desc', // 可选，排序规则
    ];
    
    $response = $deviceService->getList($params);
    print_r($response);
    
} catch (\Throwable $e) {
    // 统一处理所有异常
    echo "请求失败: " . $e->getMessage() . "\n";
    
    // 可选：获取API业务错误的详细信息
    if ($e instanceof ApiException) {
        echo "API 错误码: " . $e->getApiCode() . "\n";
        print_r($e->getRawResponse());
    }
}

异常处理

异常类型

异常属性和方法

MiotApiException

• getMessage(): string - 获取异常信息
• getCode(): int - 获取异常代码
• getPrevious(): ?Throwable - 获取原始异常

ApiException

继承自 MiotApiException，额外提供：

• getApiCode(): int - 获取 API 返回的错误码
• getRawResponse(): ?array - 获取 API 原始响应数据

HttpException

继承自 MiotApiException，额外提供：

• getHttpStatusCode(): ?int - 获取 HTTP 状态码
• getResponseData(): ?array - 获取响应数据

异常处理方式

方式一：统一使用Throwable处理（最简洁）

try {
    $params = [
        'page' => 1,
        'page_size' => 10,
        'device_name' => '测试',
    ];
    
    $response = $deviceService->getList($params);
    print_r($response);
    
} catch (\Throwable $e) {
    // 统一处理所有异常
    echo "请求失败: " . $e->getMessage() . "\n";
    
    // 可选：获取详细错误信息（如果是ApiException）
    if ($e instanceof ApiException) {
        echo "API 错误码: " . $e->getApiCode() . "\n";
        print_r($e->getRawResponse());
    }
}

方式二：分层处理（推荐，兼顾简洁和详细信息）

try {
    $params = [
        'page' => 1,
        'page_size' => 10,
        'device_name' => '测试',
    ];
    
    $response = $deviceService->getList($params);
    print_r($response);
    
} catch (ApiException $e) {
    // 优先处理API业务错误，获取详细信息
    echo "API 错误: {$e->getMessage()} (API Code: {$e->getApiCode()})\n";
    print_r($e->getRawResponse());
} catch (MiotApiException $e) {
    // 统一处理其他API客户端异常
    echo "客户端错误: {$e->getMessage()} (Code: {$e->getCode()})\n";
} catch (\Throwable $e) {
    // 捕获其他未预期的异常
    echo "未知错误: {$e->getMessage()}\n";
}

异常处理建议

1. 简单应用：可以使用 Throwable 统一处理，代码最简洁
2. 复杂应用：建议使用分层处理，获取更详细的错误信息
3. 调试阶段：使用分层处理，便于定位问题
4. 生产环境：根据实际需求选择，推荐使用分层处理

使用Throwable的优缺点

优点：

• 代码最简洁，只有一个catch块
• 可以捕获所有类型的异常和错误
• 适合快速开发和简单应用

缺点：

• 无法直接获取特定异常的额外信息
• 不利于区分不同类型的异常
• 调试时可能需要额外判断异常类型

通过 instanceof 操作符，可以在使用 Throwable 统一捕获的同时，获取特定异常的详细信息，兼顾简洁性和详细性。

注意事项

1. base_url 必填：初始化客户端时必须提供 base_url 参数，否则会抛出异常
2. Token 自动管理：客户端会自动处理 Token 的获取和刷新
3. 签名自动生成：客户端会根据请求参数自动生成签名
4. 异常处理：所有 API 调用都会抛出异常，建议使用 try-catch 进行捕获
5. SSL 验证：生产环境建议将 verify 设置为 true
6. Token 有效期：Token 有效期为 1 小时，客户端会自动刷新

接口说明

设备列表

• 接口地址：/v1/device/list
• 请求方法：GET
• 请求参数：
  • product_keys: 产品Key，多个逗号隔开（可选）
  • page: 当前页码，默认 1（可选）
  • page_size: 每页数量，默认 10，最大 50（可选）
  • device_name: 设备名称，支持模糊查询（可选）
  • sort_name: 排序字段，如：create_time, update_time，默认：create_time（可选）
  • sort_order: 排序规则，如：asc, desc，默认：desc（可选）
• 响应数据：

  {
    "code": 200,
    "message": "success",
    "data": {
      "count": 143,
      "page": 1,
      "page_size": 10,
      "list": [
        {
          "merchant_id": 25,
          "factory_code": "8H",
          "product_key": "8HM25T20251111145242",
          "iot_id": "8H2548PBN0011",
          "device_name": "TPS-65K3_00006",
          "device_secret": "79236184ebd42edbc69d9118c0640f38",
          "device_color": "N",
          "online_time": "",
          "outline_time": "",
          "status": 1,
          "burn_status": 1,
          "is_enable": 1,
          "created_at": "2025-11-26 09:41:29",
          "updated_at": "2025-11-26 11:17:43"
        }
      ]
    },
    "timestamp": 1764212395,
    "trace_id": "a09e6722-d570-4f42-b6f8-594ca96ea7ca"
  }
  

版本历史

• v1.0.0: 初始版本
  • 支持设备列表接口
  • 自动处理 token 获取和签名生成
  • 完整的异常处理体系

许可证

MIT