Techlex网关 - 接入指南

## 网关访问地址

| 环境 | 内部网关 | 外部网关 |
|------|----------|----------|
| UAT  | https://tsg-uat-internal.tqsys.cn | https://tsg-uat-external.tqls.cn |
| VER  | https://tsg-ver-internal.tqsys.cn | https://tsg-ver-external.tqls.cn |
| 生产环境`铁骑` | https://tsg-prd-internal.tqsys.cn | https://tsg-prd-external.tqls.cn |
| 生产环境`圣迪乐` | https://tsg-prd-internal.sundaily.cn | https://tsg-prd-external.sundaily.cn |

**接入说明**：内部系统接入内部网关，外部系统接入外部网关(京东、淘宝、支付宝等为外部系统)。

## 1. 鉴权

请求网关域名需要进行鉴权，具体步骤如下：

### 1.1 申请 appKey 与 appSecret

appKey/appSecret 由网关服务方分配，使用方需向服务方申请。示例如下：

- appKey：`1TEST123456781`
- appSecret：`506EEB535CF740D7A755CB4B9F4A1536`

### 1.2 访问接口路径

访问接口路径示例：`/api/service/abc`

### 1.3 生成签名值

#### 1.3.1 内部自研系统（或外部 Java 语言系统）

**方式一：集成 JAR 包**

```xml
<dependency>
    <groupId>com.techlex.web.common</groupId>
    <artifactId>public-common</artifactId>
    <version>0.1.1</version>
</dependency>
```

代码示例：
```java
public static void main(String[] args) throws Exception {
    String server = "";
    String appKey = "";
    String appSecret = "";
    String path = "";
    String timestamp = String.valueOf(LocalDateTime.now().toInstant(ZoneOffset.of("+8")).toEpochMilli());
    GateWaySign gateWaySign = new GateWaySign(server, appKey, appSecret);
    String sign = gateWaySign.getSign(timestamp, path);
}
```

**方式二：使用源代码**

```java
/**
 * 生成 Techlex 网关签名参数（需将返回的键值对放入请求头中）
 *
 * @param url       请求URL
 * @param appKey    应用密钥，用于标识调用方身份
 * @param appSecret 应用密钥，用于生成签名摘要
 * @return 包含签名所需参数的Map，需要将其中的键值对添加到HTTP请求头中
 */
public Map<String, String> getSignMap(String url, String appKey, String appSecret) {
    Logger log = LoggerFactory.getLogger(Object.class);
    log.info("开始生成 Techlex 网关签名参数，url: {}, appKey: {}", url, appKey);
    Map<String, String> map = new HashMap<>();

try {
        String timestamp = String.valueOf(LocalDateTime.now().toInstant(ZoneOffset.of("+8")).toEpochMilli());
        map.put("timestamp", timestamp);
        map.put("version", "1.0.0");

// 获取请求路径，验签时仅使用请求路径，不包含参数
        URL uri = cn.hutool.core.util.URLUtil.url(url);
        map.put("path", uri.getPath());

List<String> storedKeys = Arrays.stream(map.keySet().toArray(new String[]{})).sorted(Comparator.naturalOrder()).collect(Collectors.toList());
        final String sign = storedKeys.stream().map(key -> String.join("", key, map.get(key))).collect(Collectors.joining()).trim().concat(appSecret);
        String signLast = org.springframework.util.DigestUtils.md5DigestAsHex(sign.getBytes()).toUpperCase();
        map.put("appKey", appKey);
        map.put("sign", signLast);
        map.put("GUID", UUID.randomUUID().toString().replaceAll("-", ""));
    } catch (Exception e) {
        log.error(url + " 生成签名参数异常", e);
    }

log.info("生成 Techlex 网关签名参数完成，签名参数: {}", map);
    return map;
}
```

#### 1.3.2 外部非 Java 语言系统

**通用参数说明**

| 字段 | 值 | 描述 |
|------|-----|------|
| timestamp | 当前时间戳（13位，String类型） | 当前时间的毫秒数（有效期5分钟） |
| path | /api/service/abc | 访问的接口路径（根据实际接口变更） |
| version | 1.0.0 | 固定值，String类型 |

**签名生成流程**

1. 构造参数 Map
```java
Map<String, String> map = Maps.newHashMapWithExpectedSize(3);
map.put("timestamp", "1571711067186");
map.put("path", "/api/service/abc");
map.put("version", "1.0.0");
```

2. 参数排序与拼接
```java
List<String> storedKeys = Arrays.stream(map.keySet()
        .toArray(new String[]{}))
        .sorted(Comparator.naturalOrder())
        .collect(Collectors.toList());
final String sign = storedKeys.stream()
        .map(key -> String.join("", key, params.get(key)))
        .collect(Collectors.joining()).trim()
        .concat("506EEB535CF740D7A755CB4B9F4A1536");
```

拼接结果：`path/api/service/abctimestamp1571711067186version1.0.0506EEB535CF740D7A755CB4B9F4A1536`

3. MD5 加密并转为大写
```java
DigestUtils.md5DigestAsHex(sign.getBytes()).toUpperCase()
```

最终签名值：`A021BF82BE342668B78CD9ADE593D683`

## 2. 请求访问

### 2.1 请求路径

假设访问接口路径：`/api/service/abc`，则完整网关路径为：`{网关域名}/api/service/abc`

### 2.2 请求头

| 字段 | 值 | 描述 | 示例 |
|------|-----|------|------|
| timestamp | 时间戳 | 必填，签名时使用的时间戳 | 1571711067186 |
| appKey | AK值 | 必填，分配的AK | 1TEST123456781 |
| sign | 签名值 | 必填，生成的签名 | A90E66763793BDBC817CF3B52AAAC041 |
| version | 1.0.0 | 必填，固定值 | 1.0.0 |
| SSystem | 源系统标识 | 必填，由网关指定 | CCS |
| DSystem | 目标系统标识 | 必填，由网关指定 | SRM |
| GUID | 全局唯一标识符 | 必填 | B4FC1D30-87DF-5088-ED53-B1E0D384DC3A |

### 2.3 请求示例

#### 2.3.1 请求路径
CCS 请求 SRM 的 `/api/service/abc` 接口：
```
https://tsg-dev.tqsys.cn/api/service/abc
```

#### 2.3.2 请求头

| Key | Value |
|-----|-------|
| timestamp | 1571711067186 |
| appKey | 1TEST123456781 |
| sign | A90E66763793BDBC817CF3B52AAAC041 |
| version | 1.0.0 |
| SSystem | CCS |
| DSystem | SRM |
| GUID | B4FC1D30-87DF-5088-ED53-B1E0D384DC3A |

#### 2.3.3 请求参数
参考具体接口的业务参数要求。

### 2.4 网关常见报错

| 错误码 | 错误信息 | 解决方案 |
|--------|----------|----------|
| 401 | `sign parameters are incomplete!` 或 `signature value is error!` | 1. 检查 AK 与 SK 配置是否正确<br>2. 验证鉴权代码逻辑 |
| -107 | `divide:Can not find selector, please check your configuration!` | 检查 DSystem 参数配置是否正确 |
| -102 | `divide:Rule not found!` | 检查 divide 插件规则器中是否配置了请求路径 |
| -119 | `Can not find healthy upstream url, please check your configuration!` | 联系网关管理员检查 divide 插件的 selector 状态 |
| 500 | `Internal Server Error` | 1. 检查下游系统响应状态<br>2. 如遇超时错误，检查下游系统响应时间是否超过网关超时设置（默认3秒） |
| 200 | `success` | 认证成功，data 字段包含实际返回数据 |