Best-practices-for-a-pragmatic-restful-api

先阅读文档：http://www.oschina.net/translate/best-practices-for-a-pragmatic-restful-api 理解restful api设计理念

我们公司的所有微服务接口都放在 "api.998jk.com/微服务名" 下

微服务内部api设计规范为：业务域/访问级别, 与best-practices-for-a-pragmatic-restful-api的区别是加入了一级访问级别，例如：

简单列表接口 /chatMessage/pb GET方式，提交参数page,pageSize,total

复杂查询接口 /chatMessage/pb/search POST方式，提交参数为json RequestBody，根据各个接口不同自行定义

查询单条接口 /chatMessage/pb/123 GET方式，123为id

删除单条接口 /chatMessage/pt/123 DELETE方式，123为id

更新单条接口 /chatMessage/pt/123 PUT方式，提交参数为json RequestBody，根据各个接口不同自行定义

上述示例 完整路径为：api.998jk.com/微服务名/chatMessage/xxx

访问级别：

    pb(public) 公开，对外对内没有任何限制；

    pt(protected) 受保护，对外受保护，对内没有任何限制。需要header中含有authorization 值为"Bearer token令牌"。在api gateway会获取该token, 并且在header中设置uid 值为该令牌的用户id。

    df(default) 默认，对外加密，对内没有任何限制。继承protected限制。并且在api gateway会对返回结果加密，客户端需要对结果解密后使用。加密后json如下：

{"encrypted":"返回结果加密后的字符串"}

    pv(private) 私有的，对外无法访问，对内没有任何限制。继承default限制。

暴露的restful服务需采用JAX-RS标准注解，无需springMVC controller 直接暴露service，需要使用swagger注解以便自动产生restful api文档。示例如下

package charles.sc.provider.service;

import charles.sc.provider.entity.ChatMessage;
import com.jztey.framework.mvc.Paging;
import com.jztey.framework.mvc.RestfulPagingResult;
import com.jztey.framework.mvc.RestfulResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.cloud.netflix.feign.FeignClient;

import javax.validation.Valid;
import javax.ws.rs.*;
import javax.ws.rs.core.MediaType;

/**
 * Created by Charles on 2016/8/15.
 */
@FeignClient(value = "provider-service")
@Path("/chatMessage")
@Produces(MediaType.APPLICATION_JSON)
@Api(tags = {"聊天消息接口"})
public interface ChatMessageService {
    @Path("/pb")
    @GET
    @ApiOperation(value = "聊天记录列表", response = RestfulPagingResultChatMessage.class)
    RestfulPagingResult<ChatMessage> findPage(@QueryParam("id") int page, @QueryParam("pageSize") int pageSize, @QueryParam("total") int total);

    @Path("/pt/{id:\\d+}")
    @GET
    @ApiOperation(value = "按id查询聊天记录", response = RestfulResultChatMessage.class)
    RestfulResult<ChatMessage> find(@PathParam("id") Long id);

    @Path("/pb/search")
    @POST
    @ApiOperation(value = "搜索聊天记录", response = RestfulPagingResultChatMessage.class)
    RestfulPagingResult<ChatMessage> search(Paging<ChatMessage> paging);

    @Path("/pt")
    @POST
    @ApiOperation(value = "添加聊天记录", response = RestfulResultChatMessage.class)
    RestfulResult<ChatMessage> insert(@HeaderParam("uid") Long uid, @ApiParam @Valid ChatMessage chatMessage);

    @Path("/pt/{id:\\d+}")
    @DELETE
    @ApiOperation(value = "按id删除聊天记录", response = RestfulResultChatMessage.class)
    RestfulResult<ChatMessage> delete(@HeaderParam("uid") Long uid, @PathParam("id") Long id);

    @Path("/pt/{id:\\d+}")
    @PUT
    @ApiOperation(value = "修改聊天记录", response = RestfulResultChatMessage.class)
    RestfulResult<ChatMessage> update(@HeaderParam("uid") Long uid, @PathParam("id") Long id, @ApiParam @Valid ChatMessage chatMessage);

    class RestfulResultChatMessage extends RestfulResult<ChatMessage> {
    }

    class RestfulPagingResultChatMessage extends RestfulPagingResult<ChatMessage> {
    }
}

package charles.sc.provider.service;

import charles.sc.provider.entity.ChatMessage;
import com.jztey.framework.mvc.Paging;
import com.jztey.framework.mvc.RestfulPagingResult;
import com.jztey.framework.mvc.RestfulResult;
import org.springframework.stereotype.Service;

import java.util.ArrayList;
import java.util.List;

/**
 * Created by Charles on 2016/8/16.
 */
@com.alibaba.dubbo.config.annotation.Service
@Service
public class ChatMessageServiceImpl extends BaseService<ChatMessage> implements ChatMessageService {

    @Override
    public RestfulPagingResult<ChatMessage> findPage(int page, int pageSize, int total) {
        System.out.println("get");
        // 统一使用查询接口
        Paging<ChatMessage> paging = new Paging<>(page, pageSize);
        paging.setTotal(total);

        return this.search(paging);
    }

    @Override
    public RestfulResult<ChatMessage> find(Long id) {
        System.out.println("getById");
        return new RestfulResult(new ChatMessage(id, "fu", "tu", "msg", "mi", System.currentTimeMillis(), System.currentTimeMillis(), ChatMessage.STATUS_NO_PROCESS));
    }

    @Override
    public RestfulPagingResult<ChatMessage> search(Paging<ChatMessage> paging) {
        System.out.println("search");
        List<ChatMessage> entityList = new ArrayList<>();

        entityList.add(new ChatMessage(1L, "fu", "tu", "msg", "mi", System.currentTimeMillis(), System.currentTimeMillis(), ChatMessage.STATUS_NO_PROCESS));
        entityList.add(new ChatMessage(2L, "fu2", "tu2", "msg2", "mi2", System.currentTimeMillis(), System.currentTimeMillis(), ChatMessage.STATUS_NO_PROCESS));

        if (-1 == paging.getTotal()) {    // total没有传上来
            // 查询total
            paging.setTotal(100);
        }
        return new RestfulPagingResult(entityList, paging.getTotal());
    }

    @Override
    public RestfulResult<ChatMessage> insert(Long uid, ChatMessage chatMessage) {
        System.out.println("insert uid:" + uid);
        return new RestfulResult<>(chatMessage);
    }

    @Override
    public RestfulResult<ChatMessage> delete(Long uid, Long id) {
        System.out.println("delete uid:" + uid);
        return new RestfulResult(new ChatMessage(id, "fu", "tu", "msg", "mi", System.currentTimeMillis(), System.currentTimeMillis(), ChatMessage.STATUS_NO_PROCESS));
    }

    @Override
    public RestfulResult<ChatMessage> update(Long uid, Long id, ChatMessage chatMessage) {
        System.out.println("update uid:" + uid);
        return new RestfulResult<>(chatMessage);
    }
}

完整代码参考：http://gitlab.998jk.com/heying/spring-cloud