Restful风格接口设计从入门到埋坑

API接口设计实践

查看Restful风格各种场景下接口示例请直接跳转接口设计部分

背景

前后端开发中，后端需要为前端提供接口。那么我们如何来提供一套相对优雅的接口设计实践？

我相信许多同学都要命名困难综合征，拍脑袋的给出接口又很难形成良好的实践，那尤其如果是多人共同开发的工程，很容易就形成各种风格各立的接口，增加了一丢的不易维护。那想当然我也是其中的一员…所以这里也是给出自己的一份实践和参考。

前后端接口设计通常是Http接口。Http接口设计目前比较流行的是Restful风格接口设计。

Restful风格

得益于Http协议的相对规范与通用，有了Restful风格的接口设计。Restful的思路是将请求视为对资源的操作，用HttpMethod方法表示操作，Path表示资源路径。下面我们会大概看一下各种场景下Restful风格实践的一种思考。

Http接口设计

关于Http接口设计，我们基本遵循Restful风格，当然Restful风格不是银弹，有些情况下它并不适用，很容易挠头秃。这里我主要参考《Java开发手册》和谷歌的API设计指南。

设计约定

1. 【强制】前后端交互的 API，需要明确协议、域名、路径、请求方法、请求内容、状态码、响应体。

   1. 协议：生产环境必须使用 HTTPS
   2. 路径：每一个 API 需对应一个路径，表示 API 具体的请求地址：
      1. 代表一种资源，只能为名词，推荐使用复数，不能为动词，请求方法已经表达动作意义。
      2. URL 路径不能使用大写，单词如果需要分隔&#x