我們知道API其實(shí)就是應(yīng)用程序編程接口，可以把它理解為是一種通道，用來和不同軟件系統(tǒng)間進(jìn)行通信，本質(zhì)上它是預(yù)先定義的函數(shù)。API有很多種形式，最為常見的就是以HTTP協(xié)議來提供服務(wù)（如：RESTful），只要符合規(guī)范就可正常使用。現(xiàn)在各類企業(yè)在信息化這塊都會(huì)用到第三方提供的API，也會(huì)提供API給第三方調(diào)用，因此設(shè)計(jì)API也是需要慎重的。

具體該如何開發(fā)設(shè)計(jì)一個(gè)良好的API接口呢？

明確功能

在設(shè)計(jì)之初就需要將API詳細(xì)功能整理出來，按業(yè)務(wù)功能點(diǎn)或模塊來劃分，明確此API需要提供哪些功能。

代碼邏輯清晰

保持代碼整潔性，增加必要的注釋，接口確保功能單一，如果一個(gè)接口需要復(fù)雜的業(yè)務(wù)邏輯，建議拆分成多個(gè)接口或者將功能獨(dú)立封裝成公共方法，避免接口里代碼過多，不利于后期人員維護(hù)和后期迭代。

必要的安全校驗(yàn)機(jī)制

目前Web應(yīng)用很容易遭遇數(shù)據(jù)竊取、篡改、非法提交、重復(fù)請(qǐng)求等安全問題，API的安全校驗(yàn)機(jī)制是必不可少的。常用解決方案就是采用數(shù)字簽名形式，將每個(gè)HTTP請(qǐng)求都加上簽名，服務(wù)器端校驗(yàn)簽名合法性來保證請(qǐng)求是否合法。

日志記錄

為便于及時(shí)定位問題，日志是必不可少的。

降低耦合度

一個(gè)良好的API應(yīng)該是越簡單越好，如果API間業(yè)務(wù)耦合度過高很容易因某塊代碼異常導(dǎo)致相關(guān)API的不可用，盡可能避免API間的復(fù)雜調(diào)用關(guān)系。

返回有意義的狀態(tài)碼

API返回?cái)?shù)據(jù)中要攜帶狀態(tài)碼數(shù)據(jù)，比如200代表請(qǐng)求正常，500代表服務(wù)器內(nèi)部錯(cuò)誤等。返回通用的狀態(tài)碼有利于問題定位，比如可參考以下狀態(tài)碼：

開發(fā)文檔

既然API是提供給第三方或內(nèi)部使用的，那開發(fā)文檔是必不可少的，否則他人不知道如何調(diào)用。一個(gè)良好的API開發(fā)文檔應(yīng)包含以下元素：

1、當(dāng)前API架構(gòu)模式講解、開發(fā)工具及版本、系統(tǒng)依懶等環(huán)境信息；

2、當(dāng)前API提供哪些功能；

3、API模塊間的依懶關(guān)系；

4、調(diào)用規(guī)則、注意事項(xiàng)；

5、部署注意事項(xiàng)等。

一個(gè)好的API必然是易使用，易看懂，易擴(kuò)展，難誤用，安全性高，功能強(qiáng)大的API。要做到上面幾點(diǎn)并不容易，但是我們應(yīng)當(dāng)遵從上述原則結(jié)合業(yè)務(wù)本身合理的劃分設(shè)計(jì)API。

以上就是我的觀點(diǎn)，對(duì)于這個(gè)問題大家是怎么看待的呢？歡迎在下方評(píng)論區(qū)交流 ~ 我是科技領(lǐng)域創(chuàng)作者，十年互聯(lián)網(wǎng)從業(yè)經(jīng)驗(yàn)，歡迎關(guān)注我了解更多科技知識(shí)！

因?yàn)槲沂亲鯦ava開發(fā)的，所以就按照J(rèn)ava的開發(fā)流程說一下；首先一個(gè)好的API接口，設(shè)計(jì)是要下功夫的，細(xì)節(jié)就不在這里說了，這里還是主要說實(shí)現(xiàn)；如果開發(fā)環(huán)境具備，前后大概也就不到十分鐘，就可以完成一個(gè)簡單的API接口的開發(fā)（只是個(gè)demo）。

0、開發(fā)前準(zhǔn)備：電腦上需要安裝JDK、Maven和IDE。

1、新建一個(gè)基于Spring Boot的項(xiàng)目，為了快速完成，我選擇登錄到【

start.spring.io

2、將下載好的項(xiàng)目，解壓后引入到你的IDE中，新建一個(gè)類：

com.wukong.apidemo.controller

.ApiController

3、在這個(gè)類中增加一個(gè)方法，并主要使用@RestController、@RequestMapping、@ResponseBody兩個(gè)標(biāo)簽，整個(gè)類大概是這個(gè)樣子：

4、這時(shí)候最簡單的一個(gè)API接口就完成了，我們可以啟動(dòng)項(xiàng)目后，訪問對(duì)應(yīng)的接口地址，得到接口的返回信息：

5、我們?cè)賹?duì)這個(gè)接口稍微加工一些，讓swagger幫助我們生成一個(gè)接口文檔：

5.1、在

pom.xml

5.2、對(duì)ApiController增加：@Api、@ApiOperation、@ApiImplicitParams等標(biāo)簽：

5.3、這時(shí)候啟動(dòng)項(xiàng)目后，訪問：

http://10.141.48.41:8080/swagger-ui.html

5.4、這里留了一個(gè)小問題，swagger的配置少了一步，按照上面的做飯，訪問swagger的頁面是會(huì)報(bào)404的，大家可以嘗試解決。

我將持續(xù)分享Java開發(fā)、架構(gòu)設(shè)計(jì)、程序員職業(yè)發(fā)展等方面的見解，希望能得到你的關(guān)注。

1. 首先新建一個(gè)項(xiàng)目，然后新建一個(gè)Controller類，如下：

2. 然后類上面加上注解@RequestMapping，這個(gè)注解要帶上一個(gè)路徑，這個(gè)路徑會(huì)成為接口的一部分，然后再加上@RestController，這個(gè)注解是說明接口返回的數(shù)據(jù)格式為json，因?yàn)楝F(xiàn)在一般都是json數(shù)據(jù)格式交互

3. 接下來在類里面新建一個(gè)方法，如下：

4. 這時(shí)候我們還需要在方法上面再加上一個(gè)注解@RequestMapping，或者@GetMapping等其他注解

5. 現(xiàn)在基本一個(gè)接口就定義完了，我們?cè)诜椒ㄖ屑右稽c(diǎn)信息返回給調(diào)用方，如下：

6. 接下來我們啟動(dòng)項(xiàng)目，如下，啟動(dòng)成功

7. 最后我們打開瀏覽器，訪問我們的api接口：

API（Application Programming Interface,應(yīng)用程序編程接口），目的是提供應(yīng)用程序與開發(fā)人員基于某軟件或硬件訪問獲取數(shù)據(jù)。

api接口的返回?cái)?shù)據(jù)格式目前來說用的最多的是json數(shù)據(jù)格式。各個(gè)語言實(shí)現(xiàn)的方式有所不同，但是api使用者無須關(guān)心實(shí)現(xiàn)細(xì)節(jié)。下面是用php實(shí)現(xiàn)一個(gè)json數(shù)據(jù)格式的代碼，希望對(duì)你有所幫助。

PHP簡單示例：

假設(shè)接口訪問地址 http://127.0.0.1/api.php，api.php文件內(nèi)容是

訪問接口 http://127.0.0.1/api.php

特別說明

上術(shù)示例只是最最基本的實(shí)現(xiàn)方式上的一個(gè)小示例！市面上再復(fù)雜規(guī)范的API，無非就是一個(gè)根據(jù)客戶端的請(qǐng)求參數(shù)對(duì)數(shù)據(jù)的篩選。所以這里也給出一個(gè)比較規(guī)范的API設(shè)計(jì)思路

1. 使用標(biāo)準(zhǔn)的HTTP方法，規(guī)范路由請(qǐng)求。
   

2. 無狀態(tài)性，每個(gè)請(qǐng)求都是一個(gè)新的請(qǐng)求來對(duì)待。
   

3. 支持多種資源表示方式 (xml, json等)。
   

4. 數(shù)據(jù)格式規(guī)范化，做好數(shù)據(jù)的安全性。

作為BAT的Java開發(fā)工程師，來分享下我在公司里寫的項(xiàng)目（脫敏）中的封裝api接口部分。

我們使用的是SSM框架，但是這里其實(shí)不論是SSM還是SSH，抑或是SPRING BOOT，接下來的介紹都是通用的，因?yàn)橹饕峭ㄟ^介紹注解（annotation），而不是xml文件。

Controller.Class

首先，API接口需要出現(xiàn)在controller層，因此，在類名上方，需要至少兩個(gè)注解，@controller，用于在項(xiàng)目啟動(dòng)的時(shí)候告訴spring，這個(gè)類是controller層的，需要加載好；@requestMapping，這個(gè)注解相當(dāng)于指明了api的url中的一部分。

如果一個(gè)服務(wù)綁定的域名是

http://xx.yy.com

http://xx.yy.com/dispatch

Controller.function

看完接下來我們看函數(shù)部分，這里首先也要加一個(gè)responseBody注解，這個(gè)注解的含義是將controller層中，函數(shù)的返回對(duì)象通過轉(zhuǎn)換器，轉(zhuǎn)換為指定的格式，寫入到http response返回對(duì)象的body中去，也就是說下面這個(gè)函數(shù)返回的String，直接作為response的body內(nèi)容返回給了用戶。

接下來，依舊是requestMapping注解，相信大家也能了解了，復(fù)用上面的例子，當(dāng)url為

http://xx.yy.zz/dispatch/validate

這里大家可以能注意到了，上面的函數(shù)的參數(shù)名中用的是requestBody，而下面用的是formParam，雖然二者都是post請(qǐng)求，但是參數(shù)接收方式卻不一樣。這就意味著，代碼里指定了不同的接收方式，request的body里也必須用對(duì)應(yīng)的方式才能將數(shù)據(jù)傳遞給函數(shù)。上圖中body用raw形勢的就可以，而下圖則要求用application/x-www-form-urlencoded格式的body。

最后，上面介紹的都是post請(qǐng)求的api，下圖介紹了GET請(qǐng)求的api如何寫。可以看出，注解方面，requestMapping里指定requestMethod為GET即可。在函數(shù)的參數(shù)方面，需要用requestParma注解來接收，如下圖。當(dāng)你發(fā)送

http://xx.yy.com

以上是我的淺見，歡迎各位在下方評(píng)論區(qū)交流點(diǎn)贊。

我是蘇蘇思量，來自BAT的Java開發(fā)工程師，每日分享科技類見聞，歡迎關(guān)注我，與我共同進(jìn)步。

以python3 + PostgreSQL 為例：

術(shù)語

REST： REpresentational State Transfer

目標(biāo)

• GET - /api/Category - Retrieve all categories

• POST - /api/Category - Add a new category

• PUT - /api/Category - Update a category

• DELETE - /api/Category - Delete a category

• GET - /api/Comment - Retrieve all the stored comments

• POST - /api/Comment - Add new comment

要求

• python3.*
• PostgreSQL

requirements.txt的內(nèi)容如下：

• flask - Python的微框架

• flask_restful - 這是Flask的擴(kuò)展，可快速構(gòu)建REST API。

• flask_script - 提供了在Flask中編寫外部腳本的支持。

• flask_migrate - 使用Alembic的Flask應(yīng)用進(jìn)行SQLAlchemy數(shù)據(jù)庫遷移。

• marshmallow - ORM/ODM/框架無關(guān)的庫，用于復(fù)雜數(shù)據(jù)類型（如對(duì)象）和Python數(shù)據(jù)類型轉(zhuǎn)換。

• flask_sqlalchemy - Flask擴(kuò)展，增加了對(duì)SQLAlchemy的支持。

• flask_marshmallow - 這是Flask和marshmallow的中間層。

• marshmallow-sqlalchemy - 這是sqlalchemy和marshmallow的中間層。

• psycopg - Python的PostgreSQL API。

安裝依賴

安裝配置PostgreSQL

這里以 Ubuntu 16.04為例：

格式不太好調(diào)整， 代碼參見本人的博客： https://china-testing.github.io/flask_api.html

如果只是一個(gè)簡單API實(shí)例的話，不涉及數(shù)據(jù)庫等，可以實(shí)現(xiàn)的語言可以說非常的多，但是我覺得比較簡單的是nodejs和go 因?yàn)樗麄冇凶约旱脑?wù)模塊，nodejs有http模塊，go有net模塊，都直接可以起一個(gè)web服務(wù)，無需Apache，Tomcat等web服務(wù)器

現(xiàn)在的Web開發(fā)基本都是多端共用同一Api,也就是當(dāng)前最流行主導(dǎo)的前后端完全分離的模式去開發(fā)Api接口。

而我們通常用的最正規(guī)標(biāo)準(zhǔn)的又是Restful Api。就是在定義接口的時(shí)候不像以前那樣隨心所欲的想怎么定義就怎么定義，基本都是按照固定模式，達(dá)到見名知意基本不需要看接口注釋就知道怎么調(diào)用。

就比如，現(xiàn)在大家都默認(rèn)約定俗成的獲取統(tǒng)一用Get請(qǐng)求，新增用Post請(qǐng)求，修改用Patch請(qǐng)求，刪除用Delete請(qǐng)求，這樣對(duì)于接口使用者從接口的請(qǐng)求方式就立馬知道什么情況調(diào)用哪個(gè)指定接口，很方便高效。

API接口設(shè)計(jì)個(gè)人覺得需考慮其擴(kuò)展性能特別是對(duì)外公共接口，否則多個(gè)業(yè)務(wù)需求類似會(huì)存在兩套API的情況，比較浪費(fèi)資源。其次api名稱，請(qǐng)求參數(shù)，返回結(jié)果必須有確定含義，容易上手，返回結(jié)果一般我設(shè)計(jì)時(shí)分為2部分，系統(tǒng)層面信息，業(yè)務(wù)層面信息，系統(tǒng)層面例如api調(diào)用異常，一般用約定好的錯(cuò)誤碼標(biāo)識(shí)，業(yè)務(wù)層面就很寬泛，例如銀行業(yè)務(wù)聯(lián)網(wǎng)核查，查不到用戶信息，從系統(tǒng)層面這是OK的，業(yè)務(wù)層面肯定是不行的，不可能用戶在銀行有賬戶卻沒有用戶信息，當(dāng)然可能數(shù)據(jù)庫在做遷移導(dǎo)致暫時(shí)訪問為空，這種業(yè)務(wù)錯(cuò)誤也可以通過狀態(tài)碼或者狀態(tài)標(biāo)識(shí)boolean值+錯(cuò)誤信息返回給客戶端，這樣api出問題可以快速定位是系統(tǒng)問題還是業(yè)務(wù)問題

說明：

1）以下以

.NET為開發(fā)平臺(tái)創(chuàng)建api接口，并且引入Swagger配置接口文檔

2）

一、創(chuàng)建Net Web API項(xiàng)目

1.新建web應(yīng)用程序

2.選擇空模板，并且勾選web api

3.生成web api項(xiàng)目后，添加controller文件

4.自動(dòng)回生成content、views等文件夾及文件

5.可直接運(yùn)行，程序異常

6.Global.asax 添加配置

代碼如下：

7.修改路由配置，制定默認(rèn)controller、action

代碼如下：

8.生成默認(rèn)view

9.重新編譯，運(yùn)行程序。成功顯示home的index頁面

二、引入Swagger

1.打開NuGet程序包

2.“瀏覽”頁簽下，搜索swagger, 找到swashbuckle,右側(cè)選擇webapi項(xiàng)目，進(jìn)行安裝。

3.找到swagger.net.ui,右側(cè)選擇webapi項(xiàng)目，進(jìn)行安裝。

4.安裝完成后，生成相關(guān)配置文件，可直接關(guān)閉掉nuget,

三、配置Swagger

1.修改默認(rèn)頁（前面步驟中生成的HomeController的index頁面僅僅是測試用，到此步驟也可以刪除掉）

代碼如下：

2.運(yùn)行程序，出現(xiàn)報(bào)錯(cuò)，因?yàn)檫€缺少配置

3.打開應(yīng)用程序?qū)傩?/p>

選擇“生成”，勾選xml文檔，這個(gè)xml里面會(huì)自動(dòng)配置swagger

4.打開SwaggerNet.cs,屏蔽如下兩行代碼。

5.重新運(yùn)行，看到下面頁面則代表swagger配置成功。

四、編寫接口及調(diào)試

1.新建測試model

代碼如下：

2.新建一個(gè)測試controller

代碼如下：

3.重新運(yùn)行，看到新建的接口。

4.點(diǎn)擊“TestAPI”,再點(diǎn)擊“api/TestAPI”可打開接口詳細(xì)內(nèi)容。

5.接口測試。得到后臺(tái)返回響應(yīng)，則接口陳宮

五、注意說明

接口地址為http://localhost:64530/api/TestAPI

可利用Postman做測試