接口规范

接口地址

接口地址应遵循RESTful api规范，URL的定义应代表一种资源，不能在URL包含动词。

举个例子，假设我们对书进行增删查改，按照以前的习惯，可能我们会定义出以下接口。

方法名称	请求类型	接口地址
查找订单	GET	/getBook?id=1
删除订单	POST	/deleteBook?id=1
修改订单	POST	/updateBook?id=1
新增订单	POST	/addBook

如果以RESTful api规范来编写接口，我们给出的应该是这样:

方法名称	请求类型	接口地址
查找订单	GET	/book/{id}
删除订单	DELETE	/book/{id}
修改订单	PUT	/book/{id}
新增订单	POST	/book

可以看到用RESTful api风格表达出来的接口，URL只是标记了一个资源，具体接口做了什么动作是通过HTTP动词来表示的，比如：

HTTP动词	动作
GET	查询
POST	新增
DELETE	删除
PUT	更新

接口返回

接口会统一返回固定的数据结构，如:

{
    "code": 200,
    "data": null,
    "desc": "操作成功"
}

Controller层应继承父类cn.com.tcc.ofa.common.controller.BaseController，接口返回对象为RestData，通过父类的addRestData()方法将需要返回的对象添加进去，如无需返回数据，可不传参数。

@RestController
@RequestMapping("/admin/ofaRole")
@Api(tags = "角色控制器")
public class OfaRoleController extends BaseController {
    @ApiOperation(value = "根据id查询角色信息", response = OfaRole.class)
    @GetMapping("/role/{id}")
    public RestData<OfaRole> getRole(@PathVariable Long id) {
        OfaRole role = this.ofaRoleService.getById(id);
        return addRestData(role);
    }
}

上面代码将返回数据:

{
  "code": 200,
  "data": {
    "id": "388810757309231104",
    "roleName": "山东文化馆_超管",
    "orgId": "388810685662130176",
    "remark": null,
    "createBy": "admin",
    "createTime": "2019-11-04 19:16:14",
    "updateTime": "2019-11-04 19:16:14"
  },
  "desc": "操作成功"
}