# 新增接口

以story服务为例，新增一个获取故事内容接口

- 在controller下新建一个类，StoryDemoController.java
- 加上`@RestController`注解

```java
@RestController
public class StoryDemoController {
    
}
```

- 新增一个接口

```java
@ApiMapping(value = "story.demo.get")
public Story getStory() {
    Story story = new Story();
    story.setId(1);
    story.setName("白雪公主");
    return story;
}
```

这里的`@ApiMapping`注解作用同`@RequestMapping`注解，可以理解为是它的扩展

value就是接口名，对应客户端的`method`参数

如果要加上版本号，指定`version`参数：`@ApiMapping(value = "story.demo.get", version = "2.0")`

- 重启story服务，这样接口就可以使用了。

## 绑定业务参数

网关校验通过后，请求参数会传递到微服务上来，完整的参数如下所示：

```
请求参数：charset=utf-8&biz_content={"goods_remark":"iphone6"}&method=goods.add&format=json&app_id=2019032617262200001&sign_type=RSA2&version=1.0&timestamp=2019-04-29 19:18:38
```

其中biz_content部分是我们想要的，在方法上申明一个对象，对应biz_content中的内容即可完成参数绑定，并且对参数进行JSR-303校验。

```java
@ApiMapping(value = "goods.add")
public Object addGoods(GoodsParam param) {
    return param;
}

@Data
public class GoodsParam {
    @NotEmpty(message = "不能为空") // 支持JSR-303校验
    private String goods_remark;
}
```

一般情况下，只需要获取业务参数即可，如果想要获取更多的参数，可在后面跟一个`HttpServletRequest`对象。

```java
@ApiMapping(value = "goods.add")
public Object addGoods(GoodsParam param, HttpServletRequest request) {
    System.out.println(request.getParameter("method"));
    return param;
}
```

- 方式2

```java
@ApiMapping(value = "story.get", version = "2.2")
public Story getStory22(OpenContext<Story> openContext) {
    // 业务参数
    Story bizObject = openContext.getBizObject();
    // 获取appid，更多方法查看OpenContext类
    String appId = openContext.getAppId();
    System.out.println(appId);
    return bizObject;
}
```

另一种方式，OpenContext泛型参数填bizObject类，调用openContext.getBizObject()可直接获得对象

此方式等价于：

```java
@ApiMapping(value = "story.get", version = "2.2")
public Story getStory22(Story bizObject) {
    OpenContext openContext = ServiceContext.getCurrentContext().getOpenContext();
    String appId = openContext.getAppId();
    System.out.println(appId);
    return bizObject;
}
```

## 接口命名

接口命名没有做强制要求，但我们还是推荐按照下面的方式进行命名：

接口名的命名规则为：`服务模块.业务模块.功能模块.行为`，如：

- mini.user.userinfo.get  小程序服务.用户模块.用户信息.获取
- member.register.total.get 会员服务.注册模块.注册总数.获取

如果觉得命名规则有点长可以精简为：`服务模块.功能模块.行为`，如`member.usercount.get`，前提是确保前缀要有所区分，不和其它服务冲突。

## 测试接口

- 在sop-test工程下新建一个测试用例，`StoryDemoTest`，继承TestBase

```java
public class StoryDemoTest extends TestBase {

    String url = "http://localhost:8081/api"; // zuul
    String appId = "2019032617262200001";
    // 私钥
    String privateKey = " ";


    @Test
    public void testDemo() throws Exception {
        // 公共请求参数
        Map<String, String> params = new HashMap<String, String>();
        params.put("app_id", appId);
        // 这里对应@ApiMapping.value属性
        params.put("method", "story.demo.get");
        params.put("format", "json");
        params.put("charset", "utf-8");
        params.put("sign_type", "RSA2");
        params.put("timestamp", new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").format(new Date()));
        // 这里对应@ApiMapping.version属性
        params.put("version", "1.0");

        // 业务参数
        Map<String, String> bizContent = new HashMap<>();

        params.put("biz_content", JSON.toJSONString(bizContent));

        System.out.println("----------- 请求信息 -----------");
        System.out.println("请求参数：" + buildParamQuery(params));
        System.out.println("商户秘钥：" + privateKey);
        String content = AlipaySignature.getSignContent(params);
        System.out.println("待签名内容：" + content);
        String sign = AlipaySignature.rsa256Sign(content, privateKey, "utf-8");
        System.out.println("签名(sign)：" + sign);

        params.put("sign", sign);

        System.out.println("----------- 返回结果 -----------");
        String responseData = post(url, params);// 发送请求
        System.out.println(responseData);
    }

}
```

- 请求成功后，控制台会打印：

```
----------- 请求信息 -----------
请求参数：charset=utf-8&biz_content={}&method=story.demo.get&format=json&app_id=alipay_test&sign_type=RSA2&version=1.0&timestamp=2019-03-23 15:41:22
商户秘钥： 
待签名内容：app_id=alipay_test&biz_content={}&charset=utf-8&format=json&method=story.demo.get&sign_type=RSA2&timestamp=2019-03-23 15:41:22&version=1.0
签名(sign)：YMbxTPdovi6htcn1K3USTS6/Tbg6MOAMigG6x/kG0kQFCYH8ljvxXzcY86UT056nUG3OXxnj0xkw07eV6E03HMlu7bn3/jrT3PCcV3YguhA92aWz720x2xJWdfXY13OUPS9VOCC9zIVxu6EBD+PoZ7ojYChYvOfCR5I8bR/oOc0ZLjK63PWTBdf0eFS4sybXzRf81uNLMROsMhmBDDy0Fhml3ml77qzWBIpsmq5ECZ+89rMPbkNhAUcnFAe7ik7xZIL6WcUhAOhKVa8ZQK1GMjoGnAbGRed1FbuOHZGubgffg4/vMqrY10Bcy6h9jt/zK5w9L3HVgK3aPgQlfP16Gg==
----------- 返回结果 -----------
{"story_demo_get_response":{"msg":"Success","code":"10000","name":"白雪公主","id":1},"sign":"YMbxTPdovi6htcn1K3USTS6/Tbg6MOAMigG6x/kG0kQFCYH8ljvxXzcY86UT056nUG3OXxnj0xkw07eV6E03HMlu7bn3/jrT3PCcV3YguhA92aWz720x2xJWdfXY13OUPS9VOCC9zIVxu6EBD+PoZ7ojYChYvOfCR5I8bR/oOc0ZLjK63PWTBdf0eFS4sybXzRf81uNLMROsMhmBDDy0Fhml3ml77qzWBIpsmq5ECZ+89rMPbkNhAUcnFAe7ik7xZIL6WcUhAOhKVa8ZQK1GMjoGnAbGRed1FbuOHZGubgffg4/vMqrY10Bcy6h9jt/zK5w9L3HVgK3aPgQlfP16Gg=="}
```

## 开放现有接口

如果想把现有项目中的接口开放出去，提供给客户调用，具体操作如下：

- 将现有项目接入到SOP，前往`项目接入到SOP`文档页查看
- 在现有接口方法上加上一个注解`@ApiAbility`，如下面这个接口

```java
// 具备开放平台能力
@ApiAbility
@RequestMapping("getStory2")
public Story getStory2_0() {
    Story story = new Story();
    story.setId(1);
    story.setName("海底小纵队(默认版本号)");
    return story;
}
```

- 启动程序

这种情况下，老接口依然能正常访问，同时开放平台也能访问进来。

**注意** 此时的开放接口对应的接口名为：类@RequestMapping.value + "." + 方法@RequestMapping.value

举个列子：

```java
@RequestMapping("goods")
public class MyController {
    @ApiAbility
    @RequestMapping("listGoods")
    public Object fun() {
        
    }
}
```

fun接口对应的路径为：`/goods/listGoods`

那么对应开放平台的接口名会转换成：`goods.listGoods`，客户端的method参数要填`goods.listGoods`

当然也可以直接把@RequestMapping替换成`@ApiMapping`并指定接口名，这样的话不能兼容以前的访问形式。

