# tsm

**Repository Path**: sunxuefeng/tsm

## Basic Information

- **Project Name**: tsm
- **Description**: php 对接第三方接口SDK
- **Primary Language**: PHP
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2018-07-13
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TSM
[gitee地址](https://gitee.com/sunxuefeng/tsm)

### 项目介绍
对接第三方接口SDK

tsm, Third Services Manager 第三方服务管理器, 通过配置的方式管理多个第三方服务，适用于较为复杂的多系统交互场景

#### 安装教程

1. 下载tsm包到项目任意目录
2. require ThirdServiceManager.php文件

### 使用说明

1. 复制配置文件`config.default.php`为`config.php`, 添加第三方服务的配置信息
2. 使用配置中的第三方服务key为参数实例化一个tsm
3. 调用tsm的execute方法来调用需要的第三方服务api, 参数为配置的api的key和api要求的参数
4. 可以参照example.php来使用tsm

### 快速开始
嗯，这是一个`php`的SDK。
首先，我们需要加载tsm文件，ThirdServiceManager.php文件需要开发者自行加载，其他的文件tsm会自动加载。

``` php
require ThirdServiceManager.php
```

tsm的使用非常简单，配置好的tsm只需要两行代码就可以调用我们需要的第三方服务。

``` php
$service = \TSM\ThirdServiceManager::instance('serviceName');
$response = $service->execute('apiName', $params);
```

 `serviceName` 是配置文件中服务配置的key值，用来标记一个服务的配置。

 `apiName` 是配置文件中api配置的key值，用来标记一个api的配置。

 `$params` 是一个array，里面存放着此api需要的请求参数。

### 配置文件说明
配置文件是一个array
``` php
return array (
  'zhifubao' => array(),
  'weixin'   => array(),
  // ..
);
```
其中 `zhifubao` 就是 `serviceName`，每一个服务的相关配置放在对应array里面。
``` php
return array (
  'zhifubao' => array(
    'service' => array(),
    'apis'    => array(),
  ),
  'weixin'   => array(),
  // ..
);
```
在单个服务的配置里面有两个array，其中 `service` 表示服务的通用配置，`apis` 表示服务中各个api的配置
``` php
return array (
  'zhifubao' => array(
    'service' => array(
            'dev' => array(
                // 网关地址
                'host'          => 'http://dev.example.com:10099',
                // 签名salt值
                'signKey'       => '9efa342d13496cce8da058dc5830096d',
            ),
            'test' => array(
                // 网关地址
                'host'          => 'http://test.example.com:10099',
                // 签名salt值
                'signKey'       => '9efa342d13496cce8da058dc5830096d',
            ),
            'pdtest' => array(
                // 网关地址
                'host'          => 'http://pdtest.example.com',
                // 签名salt值
                'signKey'       => '9efa342d13496cce8da058dc5830096d',
            ),
            'product' => array(
                // 网关地址
                'host'          => 'http://www.example.com',
                // 签名salt值
                'signKey'       => '9efa342d13496cce8da058dc5830096d',
            ),
    ),
    'apis'    => array(
            /*
             * 每一个key表示api别名, 在调用第三方服务时需要用到
             */
            'detail' => array(
                // api
                'path'          => '/zeus/qxd/resale/order/detail',
                // 请求方法, 支持值: 'get', 'post'
                'method'        => 'get',
                // 接口请求重试次数, 不能是负数, 默认3次
                'retryCount'    => '4',
            ),
            'check' => array(
                'path'          => '/zeus/qxd/resale/order/detail/check',
                'method'        => 'get',
            ),
            'confirm' => array(
                'path'          => '/zeus/qxd/resale/order/detail/confirm',
                'method'        => 'get',
            ),
    ),
  ),
  'weixin'   => array(),
  // ..
);
```
`service` 中，通过键值标记不同的开发环境，具体我们会在`环境切换`小结讨论。每个键值包含若干值。

| 键值 | 说明 | 默认值 |
| :--- | :--- | :--- |
| host | 服务地址 | null |

开发者也可以自定义其他配置，通过 `BaseService` 中的 `getCommonConfig` 方法获取，具体我们在 `第三方服务管理扩展` 讨论。
`apis` 中，包含了此服务所有api的配置。通过键值表示此api的别名，array的内容包含若干值。

| 键值 | 说明 | 默认值 |
| :--- | :--- | :--- |
| path | 接口path | null |
| method | 请求方式 | post |
| retryCount | 请求次数 | 3 |

开发者也可以自定义其他配置，通过 `BaseService` 中的 `getApiConfig` 方法获取，具体我们在 `第三方服务管理扩展` 讨论。
这样，一个第三方服务就对接完成了

### 环境切换
对接第三方服务，一般都会有两三套环境。在不同的环境上，地址以及签名salt值等都会有差别。在配置中可以通过 `service` 下的key值来切换不同的环境。
``` php
return array (
  'zhifubao' => array(
    'service' => array(
            'dev' => array(
                // 网关地址
                'host'          => 'http://dev.example.com:10099',
                // 签名salt值
                'signKey'       => '9efa342d13496cce8da058dc5830096d',
            ),
            'test' => array(
                // 网关地址
                'host'          => 'http://test.example.com:10099',
                // 签名salt值
                'signKey'       => '9efa342d13496cce8da058dc5830096d',
            ),
            'pdtest' => array(
                // 网关地址
                'host'          => 'http://pdtest.example.com',
                // 签名salt值
                'signKey'       => '9efa342d13496cce8da058dc5830096d',
            ),
            'product' => array(
                // 网关地址
                'host'          => 'http://www.example.com',
                // 签名salt值
                'signKey'       => '9efa342d13496cce8da058dc5830096d',
            ),
    ),
    'apis'    => array(
           // ..
    ),
  ),
  'weixin'   => array(),
  // ..
);
```
诸如dev、test之类的值，可以通过配置文件中的APP_ENV来指定。
``` php
define(APP_ENV, 'dev');
```
tsm会根据APP_ENV来切换环境。
> 推荐使用如下方式来指定APP_ENV的值，在php.ini中自定义一个tsm.env的值，通过get_cfg_var函数来获取这个值。这样可以更灵活的指定环境而不需要修改代码。
``` php
define(APP_ENV, get_cfg_var(tsm.env));    // tsm.env 为php.ini中增加的一个自定义的配置值
```

### 第三方服务管理扩展
访问第三方接口一般需要数据签名或者数据加解密来认证，`tsm` 提供了灵活的方式来扩展程序。
在 `tsm` 的services文件中，新建一个名为、\*\*\*Service.php的文件并完成一个同名的类，此类需要继承BaseService。
> 注意 `***` 要跟配置文件中的拼写 `serviceName` 保持一致并且开头字母大写，例如配置的serviceName为 'example'，那么新建的文件名字为ExampleService.php，类名为class ExampleServcie

开发者可以重写 `generateParams` 方法以及 `handleResponse` 方法。
在 `generateParams` 方法中，可以进行数据发送前的数据重新组装，签名计算，数据加密等操作。
在 `handleResponse` 方法中，可以进行数据返回后的数据验签，数据解密等操作。

另外，BaseService提供了如下不可重写的方法来读取通用配置和api配置。

| 方法名称 | 参数 | 返回值 | 作用 |
| :--- | :--- | :--- | :--- |
| getCommonConfig | 配置key | 配置值 | 获取自定义的通用配置 |
| getApiConfig | api key | api配置值(array) | 获取api相关配置数组 |