# MockStore 在线接口调用说明

NEI 目前已经发布了获取接口响应结果的 Mock 数据的在线接口，接口可以跨域调用，方便开发人员在本地测试接口，现说明如下：

## 请求地址

Mock 地址一：

```html
https://nei.netease.com/api/apimock/:projectKey/:apiPath
```

Mock 地址二：

```html
https://nei.netease.com/api/apimock-v2/:progroupKey/:apiPath
```

> 说明：Mock 地址一，是在某个项目中查找匹配的接口，查找速度快，推荐使用。Mock 地址二，是在某个项目组中查找匹配的接口，由于项目组中接口的数量可能会很多，所以查找速度比较慢，具体要看项目组中的接口数量。如果想在同个工程中调用多个项目中的接口，此时可以使用“Mock 地址二”，因为在同个项目组中的接口，请求地址的前缀`https://nei.netease.com/api/apimock-v2/:progroupKey/`都是一样的，配置起来很方便。

## 参数说明

| 名称 | 类型 | 是否必需 | 说明 |
| :--- | :--- | :--- | :--- |
| projectKey | String | 是 | 项目的唯一标识 Key，在项目的设置中查看 |
| progroupKey | String | 是 | 项目组的唯一标识 Key，在项目组的设置中查看 |
| apiPath | String | 是 | NEI 中定义的接口地址 |

> 注意：
> - 请求的 method 必须和 NEI 中的定义保持一致。
> - 如果找到多个符合要求的接口，则返回的接口是随机的，其他情况见[查询参数的匹配规则](#查询参数的匹配规则)的说明。
> - 返回的 Mock 数据已经持久化。
> - projectKey 是项目的唯一标识，查看方式：[查看项目的 Key](./查看项目的Key.md)。
> - progroupKey 是项目组的唯一标识，查看方式是类似的。

## 获取指定版本的接口

如果要获取指定版本的接口，需要将版本名称放在请求头 `nei-api-version` 中：

| 请求头名称 | 类型 | 是否必需 | 说明 |
| :--- | :--- | :--- | :--- |
| nei-api-version | String | 否 | 它的值就是接口的版本名称 |

## 查询参数的匹配规则

一般来说，如果接口的 method 和 path（请求地址，不包含查询参数）一样，则它们是同一个接口。

但有时候，我们希望可以通过查询参数映射到 Controller 或者 Service 的不同方法，比如下面两个接口 A 和 B：

接口 A：
```html
POST /api/users/:id
```

接口 B：
```html
POST /api/users/:id?lock
```

接口 A 是修改用户信息，接口 B 是锁定用户，这在后端肯定有两个对应的方法，可以在 Controller 中通过查询参数的不同，调用不同的 Service 方法。

考虑到上述原因，在查询目标接口时，会匹配查询参数并且遵循最大匹配原则，即：

- 接口定义中的请求地址（注意，是 NEI 平台上定义的请求地址，不包含请求参数），如果有查询参数，则在实际请求中，这些查询参数**必须全部出现，只能多不能少**。
- 如果匹配到了多个接口，则请求地址长度最长的接口胜出。

比如，如果实际请求是：

```html
POST /api/users/:123?lock
```

则接口 A 和接口 B 都匹配，因为接口 B 的请求地址长度大于接口 A 的请求地址长度，所以最终匹配的是接口 B。

再比如，如果实际请求是：

```html
POST /api/users/123
```

则只有接口 A 匹配，因为接口 B 中的查询参数 `lock` 在实际请求中不存在，匹配失败。所以最终匹配的是接口 A。

## 代码示例以及实现文档

MockStore 一共支持 11 种场景，具体的调用方式和说明请参考 [MockStore 代码示例](./mockstore示例代码.md)。

在编写具体的代码时，MockStore 也考虑到了较多的实际场景，比如参数的传递并不会只限制特定的方式，具体实现逻辑请查看 [MockStore 实现说明](./mockstore实现说明.md)。

## FAQ

>在线接口返回 403 没权限是怎么回事？

- 请检查接口的发送方式是否正确，注意，在浏览器中直接访问是 `GET` 方式，其他方式需要使用其他工具，比如 [phosphorus](<https://nei.netease.com/phosphorus>)。
- 请检查项目的 Key 是否正确。

>有些字段前端无法发送，比如数据模型的 createTime 字段，这种情况如何解决？

- 可以使用前置业务逻辑脚本对请求发送过来的数据进行修改，请参考 [MockStore 示例代码文档](./mockstore示例代码.md#创建单个分组)。

>可以对请求参数做基本的检验吗？

- 可以使用前置业务逻辑脚本对请求参数做基本的检验，检测到有不合法的参数可以直接报错返回，请参考[MockStore 实现说明文档](./mockstore实现说明.md#前置业务逻辑脚本)。

>可以实现分页的功能吗？

- 可以使用后置业务逻辑脚本，在返回数据之前根据请求的查询参数信息，返回用户要想要的分页数据，请参考 [MockStore 示例代码文档](./mockstore示例代码.md#加载所有用户-支持分页)。

>为什么接口返回的数据和定义的不一致，而且修改了接口定义也无效？

- 此时一般是接口匹配错了，请检查项目中是否有相同请求地址的接口。注意，接口匹配时，是不会判断请求参数的，可以通过路径参数区分。

>调用接口的时候，都会发生哪些异常？

- 如果生成 Mock 数据的过程中有错误发生，则会把错误信息放在响应结果的 `_nei_apimock_error` 字段中。比如生成规则的代码有语法错误等。
- 如果生成 Mock 数据花费的时间超过 1000 毫秒，则会报超时错误，此时响应结果是 `Script execution timed out.`。比如生成规则中有死循环。
- 前置或者后置业务逻辑脚本有异常。

>能否模拟接口响应延时

- 可以。在接口详情页面中可以设置延时时间，也就是 `Mock 请求延时响应毫秒数` 的值，它是一个毫秒数值。