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

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

明確功能

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

代碼邏輯清晰

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

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

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

日志記錄

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

降低耦合度

一個(gè)良好的API應(yīng)該是越簡(jiǎn)單越好，如果API間業(yè)務(wù)耦合度過(guò)高很容易因某塊代碼異常導(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)碼有利于問(wèn)題定位，比如可參考以下?tīng)顟B(tài)碼：

開(kāi)發(fā)文檔

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

1、當(dāng)前API架構(gòu)模式講解、開(kāi)發(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è)問(wèn)題大家是怎么看待的呢？歡迎在下方評(píng)論區(qū)交流 ~ 我是科技領(lǐng)域創(chuàng)作者，十年互聯(lián)網(wǎng)從業(yè)經(jīng)驗(yàn)，歡迎關(guān)注我了解更多科技知識(shí)！

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

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

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

start.spring.io

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

com.wukong.apidemo.controller

.ApiController

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

4、這時(shí)候最簡(jiǎn)單的一個(gè)API接口就完成了，我們可以啟動(dòng)項(xiàng)目后，訪問(wèn)對(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)目后，訪問(wèn)：

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

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

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

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

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

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

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

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

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

7. 最后我們打開(kāi)瀏覽器，訪問(wèn)我們的api接口：

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

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

PHP簡(jiǎn)單示例：

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

訪問(wèn)接口 http://127.0.0.1/api.php

特別說(shuō)明

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

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

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

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

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

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

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

Controller.Class

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

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

http://xx.yy.com

http://xx.yy.com/dispatch

Controller.function

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

接下來(lá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形勢(shì)的就可以，而下圖則要求用application/x-www-form-urlencoded格式的body。

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

http://xx.yy.com

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

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

API接口是我們?cè)诙鄠�(gè)模塊之間調(diào)用、協(xié)作是常用的一種方式，大多數(shù)編程語(yǔ)言都會(huì)考慮到這一點(diǎn)，因此，也都有高效實(shí)現(xiàn)API接口的方式，例如，

• Python的flask
  

• Java的Spring Boot

以Python的flask為例，我們可以輕松實(shí)現(xiàn)一個(gè)api接口，

Spring Boot實(shí)現(xiàn)API接口的示例這里就不展示了，SpringBoot已經(jīng)把開(kāi)發(fā)流程簡(jiǎn)化的非常徹底了，比較簡(jiǎn)單。

這里，針對(duì)Python 我推薦一款開(kāi)發(fā)API接口的第三方包，近期非常受歡迎，它就是fastapi。

鏈接：https://github.com/tiangolo/fastapi

Star：10.4k

fastapi是一款快速、高效的api接口開(kāi)發(fā)工具，它具有如下特性，

快速：非常高的性能，與NodeJS和Go相當(dāng)（感謝Starlette和Pydantic）。最快的Python框架之一。

• 快速編碼：將開(kāi)發(fā)特性的速度提高大約200%到300%。

• 更少的錯(cuò)誤：減少大約40%的由人類(lèi)（開(kāi)發(fā)人員）引起的錯(cuò)誤。

• 直觀：強(qiáng)大的編輯器支持。到處都是。更少的調(diào)試時(shí)間。

• 簡(jiǎn)單：易于使用和學(xué)習(xí)。減少閱讀文檔的時(shí)間。

• 簡(jiǎn)而言之：最小化代碼重復(fù)。每個(gè)參數(shù)聲明有多個(gè)特性。

• 健壯：獲得生產(chǎn)準(zhǔn)備代碼，自動(dòng)交互文檔。

• 基于標(biāo)準(zhǔn)：基于（并且完全兼容）api的開(kāi)放標(biāo)準(zhǔn)。

感興趣的可以嘗試一下。

如果覺(jué)得有幫助的話(huà)，麻煩幫忙點(diǎn)個(gè)贊再走吧~

以python3 + PostgreSQL 為例：

術(shù)語(yǔ)

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中編寫(xiě)外部腳本的支持。

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

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

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

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

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

• psycopg - Python的PostgreSQL API。

安裝依賴(lài)

安裝配置PostgreSQL

這里以 Ubuntu 16.04為例：

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

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

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

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

API接口設(shè)計(jì)個(gè)人覺(jué)得需考慮其擴(kuò)展性能特別是對(duì)外公共接口，否則多個(gè)業(yè)務(wù)需求類(lèi)似會(huì)存在兩套API的情況，比較浪費(fèi)資源。其次api名稱(chēng)，請(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)核查，查不到用戶(hù)信息，從系統(tǒng)層面這是OK的，業(yè)務(wù)層面肯定是不行的，不可能用戶(hù)在銀行有賬戶(hù)卻沒(méi)有用戶(hù)信息，當(dāng)然可能數(shù)據(jù)庫(kù)在做遷移導(dǎo)致暫時(shí)訪問(wèn)為空，這種業(yè)務(wù)錯(cuò)誤也可以通過(guò)狀態(tài)碼或者狀態(tài)標(biāo)識(shí)boolean值+錯(cuò)誤信息返回給客戶(hù)端，這樣api出問(wèn)題可以快速定位是系統(tǒng)問(wèn)題還是業(yè)務(wù)問(wèn)題