接口开发 · FA+Ecloud互联网应用开发平台综合技术入门指南(READ)

## 一、概述如何在新的RayOauthServer中，定义一个对外提供服务的接口呢？ ## 二、基本概念 ### **接口类型** 依据响应的模式不同，可以分为同步接口和异步接口；所谓同步接口：就是第三方系统调用的时候，立刻返回响应接口的接口；所谓异步接口：就是第三方系统调用的时候，由于响应时间或其他因素导致不能立刻返回执行结果的接口；这种接口调用的时候，仅记录下操作请求，后续有调度服务（平台的另外一个容器组件，调度服务组件来执行）； ## 三、从零开始开发一个接口 ### **关键要点** 1、每个接口都包含了一个定义controller（继承自RayOauthApiController）和一个实现service（继承自RayOauthApiService），且定义在一个类文件中即可； 2、定义一个apiRequestSimpleUrl变量，设定该api的简明url（与固定前缀一起构成完整的URL）； 3、接口的业务参数，都定义为@RequestHeader(required = false)和@RequestParam(required = false)，使用业务校验方法提供校验逻辑和提示； 4、如果是同步接口，则核心业务实现在doImmediatelyWhenImSync； 5、如果是异步接口，则核心业务实现在doLaterInJobWhenImAsyn； ### **同步接口** ``` @RestController public class RayOauthApiSampleSync extends RayOauthApiController { @Autowired private RayOauthApiSampleSyncService rayOauthApiSampleService; private static final String apiRequestSimpleUrl = "/sample/sync"; @PostMapping(RayOauthServerConstants.rayOauthApiUrlPrefix + apiRequestSimpleUrl) public ResponseEntity<ResponseObject> view(@RequestHeader(required = false) String rayOauthServerAppId, @RequestHeader(required = false) String rayOauthServerTimeStamp, @RequestHeader(required = false) String rayOauthServerSignature, @RequestParam(required = false) int testParamInt, @RequestParam(required = false) String testParamString) throws Exception { return ResponseEntity.ok(rayOauthApiSampleService.response(getOauthClient(), getOauthApi(), getOauthApiRequest(), getOauthRequestParameters())); } public static class RayOauthApiSampleSyncModel extends RayModel { } @Service public static class RayOauthApiSampleSyncService extends RayOauthApiService<RayOauthApiSampleSyncModel> { @Autowired private SysLogDao sysLogDao; @Override public String simpleUrl() { return apiRequestSimpleUrl; } @Override public void validatingParameters(OauthClient oauthClient, OauthApi oauthApi, ResponseObject responseObj, RayOauthServerParameterValidator rayOauthServerParameterValidator) throws Exception { rayOauthServerParameterValidator.checkParameterIsNotEmpty("testParamString"); rayOauthServerParameterValidator.checkParameterIsInteger("testParamInt"); } @Override public ResponseObject doImmediatelyWhenImSync(OauthClient oauthClient, OauthApiRequest oauthApiRequest, RequestParameters requestParamaters) throws Exception { String testParamString = requestParamaters.getString("testParamString"); int testParamInt = requestParamaters.getInteger("testParamInt"); Specification<SysLog> spec = new Specification<SysLog>() { @Override public Predicate toPredicate(Root<SysLog> root, CriteriaQuery<?> query, CriteriaBuilder criteriaBuilder) { List<Predicate> predicates = new ArrayList<>(); if (!StringUtil.isEmpty(testParamString)) { predicates.add(criteriaBuilder.like(root.get("infoCode"), wrapLike(testParamString))); } return criteriaBuilder.and(predicates.toArray(new Predicate[predicates.size()])); } }; model.setPageobject(PageProcessor.reasonablePage(sysLogDao, spec, 1, testParamInt, "", "")); return responseObj; } @Override public AsynApiResult doLaterInJobWhenImAsyn(OauthClient oauthClient, OauthApiRequest oauthApiRequest, OauthApi oauthApi, RequestParameters requestParamaters) { return null; } @Override public String apiName() { return "同步接口示范"; } @Override public long responseMode() { return ResponseMode.IMMEDIATELY_SYN; } @Override public boolean isLimitRequestRate() { return true; } } } ``` ### **异步接口** ``` @RestController public class RayOauthApiSampleAsyn extends RayOauthApiController { @Autowired private RayOauthApiSampleAsynService rayOauthApiSampleService; private static final String apiRequestSimpleUrl = "/sample/asyn"; @PostMapping(RayOauthServerConstants.rayOauthApiUrlPrefix + apiRequestSimpleUrl) public ResponseEntity<ResponseObject> view(@RequestHeader(required = false) String rayOauthServerAppId, @RequestHeader(required = false) String rayOauthServerTimeStamp, @RequestHeader(required = false) String rayOauthServerSignature, @RequestParam(required = false) int testParamInt, @RequestParam(required = false) String testParamString) throws Exception { return ResponseEntity.ok(rayOauthApiSampleService.response(getOauthClient(), getOauthApi(), getOauthApiRequest(), getOauthRequestParameters())); } public static class RayOauthApiSampleModel extends RayModel { } @Service public static class RayOauthApiSampleAsynService extends RayOauthApiService<RayOauthApiSampleModel> { @Autowired private SysLogDao sysLogDao; @Override public String simpleUrl() { return apiRequestSimpleUrl; } @Override public void validatingParameters(OauthClient oauthClient, OauthApi oauthApi, ResponseObject responseObj, RayOauthServerParameterValidator rayOauthServerParameterValidator) throws Exception { rayOauthServerParameterValidator.checkParameterIsNotEmpty("testParamString"); rayOauthServerParameterValidator.checkParameterIsInteger("testParamInt"); } @Override public ResponseObject doImmediatelyWhenImSync(OauthClient oauthClient, OauthApiRequest oauthApiRequest, RequestParameters requestParamaters) throws Exception { model.setMessage("异步操作,已经被记录"); return responseObj; } @Override public AsynApiResult doLaterInJobWhenImAsyn(OauthClient oauthClient, OauthApiRequest oauthApiRequest, OauthApi oauthApi, RequestParameters requestParamaters) { AsynApiResult result = AsynApiResult.instance(); String testParamString = requestParamaters.getString("testParamString"); int testParamInt = requestParamaters.getInteger("testParamInt"); result.setExecutionData("testParamInt:" + testParamInt + ",testParamString:" + testParamString).setSuccess(true); return result; } @Override public String apiName() { return "异步接口示范"; } @Override public long responseMode() { return ResponseMode.LATER_ASYN; } @Override public boolean isLimitRequestRate() { return false; } } } ``` ### **数据传递** validatingParameters中进行参数验证，可以通过model对象作为中介，传递数据到doImmediatelyWhenImSync；举例： ``` @Override public void validatingParameters(OauthClient oauthClient, OauthApi oauthApi, ResponseObject responseObj, RayOauthServerParameterValidator rayOauthServerParameterValidator) throws Exception { rayOauthServerParameterValidator.checkParameterIsNotEmpty("userCode"); String userCode = rayOauthServerParameterValidator.getString("userCode"); CardInfo cardinfo = cardInfoDao.findByUserCode(userCode); model.setCardinfo(cardinfo); } @Override public ResponseObject doImmediatelyWhenImSync(OauthClient oauthClient, OauthApiRequest oauthApiRequest, RequestParameters requestParamaters) throws Exception { CardInfo cardinfo = model.getCardinfo(); return responseObj; } ```