1.Web應(yīng)用模式佛寿,
在開(kāi)發(fā)Web應(yīng)用中默责,有兩種模式:
1.1前段后端不分離(耦合度高壶熏,適合純網(wǎng)頁(yè)的應(yīng)用>淠)
在前后端不分離的應(yīng)用模式中,前端頁(yè)面看到的效果都是由后端控制棒假,由后端渲染頁(yè)面或重定向俄占,也就是后端需要控制前端的展示,前端與后端的耦合度很高淆衷。
應(yīng)用場(chǎng)景分析:
這種應(yīng)用模式比較適合純網(wǎng)頁(yè)應(yīng)用,但是當(dāng)后端對(duì)接App時(shí)渤弛,App可能并不需要后端返回一個(gè)HTML網(wǎng)頁(yè)祝拯,而僅僅是數(shù)據(jù)本身,所以后端原本返回網(wǎng)頁(yè)的接口不再適用于前端App應(yīng)用她肯,為了對(duì)接App后端還需再開(kāi)發(fā)一套接口佳头。
1.2前段后端分離(耦合度低,前端通過(guò)訪問(wèn)接口來(lái)對(duì)數(shù)據(jù)進(jìn)行增刪改查)
在前后端分離的應(yīng)用模式中晴氨,后端僅返回前端所需的數(shù)據(jù)康嘉,不再渲染HTML頁(yè)面,不再控制前端的效果籽前。至于前端用戶看到什么效果亭珍,從后端請(qǐng)求的數(shù)據(jù)如何加載到前端中,都由前端自己決定枝哄,網(wǎng)頁(yè)有網(wǎng)頁(yè)的處理方式肄梨,App有App的處理方式,但無(wú)論哪種前端挠锥,所需的數(shù)據(jù)基本相同众羡,后端僅需開(kāi)發(fā)一套邏輯對(duì)外提供數(shù)據(jù)即可。
在前后端分離的應(yīng)用模式中 蓖租,前端與后端的耦合度相對(duì)較低粱侣。
在前后端分離的應(yīng)用模式中,我們通常將后端開(kāi)發(fā)的每個(gè)視圖都稱(chēng)為一個(gè)接口蓖宦,或者API齐婴,前端通過(guò)訪問(wèn)接口來(lái)對(duì)數(shù)據(jù)進(jìn)行增刪改查。
- RESTful設(shè)計(jì)方法
2.1域名
應(yīng)該盡量將API部署在專(zhuān)用域名之下稠茂。
https://api.example.com
如果確定API很簡(jiǎn)單尔店,不會(huì)有進(jìn)一步擴(kuò)展,可以考慮放在主域名下。
2.2版本
應(yīng)該將API的版本號(hào)放入U(xiǎn)RL嚣州。
http://www.example.com/app/1.0/foo
http://www.example.com/app/1.1/foo
http://www.example.com/app/2.0/foo
另一種做法是鲫售,將版本號(hào)放在HTTP頭信息中,但不如放入U(xiǎn)RL方便和直觀该肴。Github采用這種做法情竹。
因?yàn)椴煌陌姹荆梢岳斫獬赏环N資源的不同表現(xiàn)形式匀哄,所以應(yīng)該采用同一個(gè)URL秦效。版本號(hào)可以在HTTP請(qǐng)求頭信息的Accept字段中進(jìn)行區(qū)分(參見(jiàn)Versioning REST Services):
Accept: vnd.example-com.foo+json; version=1.0
Accept: vnd.example-com.foo+json; version=1.1
Accept: vnd.example-com.foo+json; version=2.0
2.3路徑
路徑又稱(chēng)"終點(diǎn)"(endpoint),表示API的具體網(wǎng)址涎嚼,每個(gè)網(wǎng)址代表一種資源(resource)
(1) 資源作為網(wǎng)址阱州,只能有名詞,不能有動(dòng)詞法梯,而且所用的名詞往往與數(shù)據(jù)庫(kù)的表名對(duì)應(yīng)苔货。
舉例來(lái)說(shuō),以下是不好的例子:
/getProducts
/listOrders
/retreiveClientByOrder?orderId=1
對(duì)于一個(gè)簡(jiǎn)潔結(jié)構(gòu)立哑,你應(yīng)該始終用名詞夜惭。 此外,利用的HTTP方法可以分離網(wǎng)址中的資源名稱(chēng)的操作铛绰。
GET /products :將返回所有產(chǎn)品清單
POST /products :將產(chǎn)品新建到集合
GET /products/4 :將獲取產(chǎn)品 4
PATCH(或)PUT /products/4 :將更新產(chǎn)品 4
(2) API中的名詞應(yīng)該使用復(fù)數(shù)诈茧。無(wú)論子資源或者所有資源里伯。
舉例來(lái)說(shuō)拷泽,獲取產(chǎn)品的API可以這樣定義
獲取單個(gè)產(chǎn)品:http://127.0.0.1:8080/AppName/rest/products/1
獲取所有產(chǎn)品: http://127.0.0.1:8080/AppName/rest/products
2.4 HTTP動(dòng)詞
對(duì)于資源的具體操作類(lèi)型,由HTTP動(dòng)詞表示陷谱。
常用的HTTP動(dòng)詞有下面四個(gè)(括號(hào)里是對(duì)應(yīng)的SQL命令)这嚣。
GET(SELECT):從服務(wù)器取出資源(一項(xiàng)或多項(xiàng))走触。
POST(CREATE):在服務(wù)器新建一個(gè)資源。
PUT(UPDATE):在服務(wù)器更新資源(客戶端提供改變后的完整資源)疤苹。
DELETE(DELETE):從服務(wù)器刪除資源互广。
還有三個(gè)不常用的HTTP動(dòng)詞。
PATCH(UPDATE):在服務(wù)器更新(更新)資源(客戶端提供改變的屬性)卧土。
HEAD:獲取資源的元數(shù)據(jù)惫皱。
OPTIONS:獲取信息,關(guān)于資源的哪些屬性是客戶端可以改變的尤莺。
下面是一些例子旅敷。
GET /zoos:列出所有動(dòng)物園
POST /zoos:新建一個(gè)動(dòng)物園(上傳文件)
GET /zoos/ID:獲取某個(gè)指定動(dòng)物園的信息
PUT /zoos/ID:更新某個(gè)指定動(dòng)物園的信息(提供該動(dòng)物園的全部信息)
PATCH /zoos/ID:更新某個(gè)指定動(dòng)物園的信息(提供該動(dòng)物園的部分信息)
DELETE /zoos/ID:刪除某個(gè)動(dòng)物園
GET /zoos/ID/animals:列出某個(gè)指定動(dòng)物園的所有動(dòng)物
DELETE /zoos/ID/animals/ID:刪除某個(gè)指定動(dòng)物園的指定動(dòng)物
2.5 過(guò)濾信息
如果記錄數(shù)量很多,服務(wù)器不可能都將它們返回給用戶颤霎。API應(yīng)該提供參數(shù)媳谁,過(guò)濾返回結(jié)果涂滴。
下面是一些常見(jiàn)的參數(shù)。
?limit=10:指定返回記錄的數(shù)量
?offset=10:指定返回記錄的開(kāi)始位置晴音。
?page=2&per_page=100:指定第幾頁(yè)柔纵,以及每頁(yè)的記錄數(shù)。
?sortby=name&order=asc:指定返回結(jié)果按照哪個(gè)屬性排序锤躁,以及排序順序搁料。
?animal_type_id=1:指定篩選條件
參數(shù)的設(shè)計(jì)允許存在冗余,即允許API路徑和URL參數(shù)偶爾有重復(fù)系羞。比如郭计,GET /zoos/ID/animals 與 GET /animals?zoo_id=ID 的含義是相同的。
2.6 狀態(tài)嗎
服務(wù)器向用戶返回的狀態(tài)碼和提示信息椒振,常見(jiàn)的有以下一些(方括號(hào)中是該狀態(tài)碼對(duì)應(yīng)的HTTP動(dòng)詞)昭伸。
200 OK - [GET]:服務(wù)器成功返回用戶請(qǐng)求的數(shù)據(jù)
201 CREATED - [POST/PUT/PATCH]:用戶新建或修改數(shù)據(jù)成功。
202 Accepted - []:表示一個(gè)請(qǐng)求已經(jīng)進(jìn)入后臺(tái)排隊(duì)(異步任務(wù))
204 NO CONTENT - [DELETE]:用戶刪除數(shù)據(jù)成功澎迎。
400 INVALID REQUEST - [POST/PUT/PATCH]:用戶發(fā)出的請(qǐng)求有錯(cuò)誤庐杨,服務(wù)器沒(méi)有進(jìn)行新建或修改數(shù)據(jù)的操作
401 Unauthorized - []:表示用戶沒(méi)有權(quán)限(令牌、用戶名嗡善、密碼錯(cuò)誤)。
403 Forbidden - [] 表示用戶得到授權(quán)(與401錯(cuò)誤相對(duì))学歧,但是訪問(wèn)是被禁止的罩引。
404 NOT FOUND - []:用戶發(fā)出的請(qǐng)求針對(duì)的是不存在的記錄,服務(wù)器沒(méi)有進(jìn)行操作枝笨,該操作是冪等的袁铐。
406 Not Acceptable - [GET]:用戶請(qǐng)求的格式不可得(比如用戶請(qǐng)求JSON格式,但是只有XML格式)横浑。
410 Gone -[GET]:用戶請(qǐng)求的資源被永久刪除剔桨,且不會(huì)再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 當(dāng)創(chuàng)建一個(gè)對(duì)象時(shí)徙融,發(fā)生一個(gè)驗(yàn)證錯(cuò)誤洒缀。
500 INTERNAL SERVER ERROR - [*]:服務(wù)器發(fā)生錯(cuò)誤,用戶將無(wú)法判斷發(fā)出的請(qǐng)求是否成功欺冀。
狀態(tài)碼的完全列表參見(jiàn)這里或這里树绩。
2.7錯(cuò)誤處理
如果狀態(tài)碼是4xx,服務(wù)器就應(yīng)該向用戶返回出錯(cuò)信息隐轩。一般來(lái)說(shuō)饺饭,返回的信息中將error作為鍵名,出錯(cuò)信息作為鍵值即可职车。
{
error: "Invalid API key"
}
2.8返回結(jié)果
針對(duì)不同操作瘫俊,服務(wù)器向用戶返回的結(jié)果應(yīng)該符合以下規(guī)范鹊杖。
GET /collection:返回資源對(duì)象的列表(數(shù)組)
GET /collection/resource:返回單個(gè)資源對(duì)象
POST /collection:返回新生成的資源對(duì)象
PUT /collection/resource:返回完整的資源對(duì)象
PATCH /collection/resource:返回完整的資源對(duì)象
DELETE /collection/resource:返回一個(gè)空文檔
2.9超媒體(Hypermedia API)
RESTful API最好做到Hypermedia(即返回結(jié)果中提供鏈接,連向其他API方法)扛芽,使得用戶不查文檔骂蓖,也知道下一步應(yīng)該做什么。
比如胸哥,Github的API就是這種設(shè)計(jì)涯竟,訪問(wèn)api.github.com會(huì)得到一個(gè)所有可用API的網(wǎng)址列表。
{
"current_user_url": "https://api.github.com/user",
"authorizations_url": "https://api.github.com/authorizations",
// ...
}
從上面可以看到空厌,如果想獲取當(dāng)前用戶的信息庐船,應(yīng)該去訪問(wèn)api.github.com/user,然后就得到了下面結(jié)果嘲更。
{
"message": "Requires authentication",
"documentation_url": "https://developer.github.com/v3"
}
上面代碼表示筐钟,服務(wù)器給出了提示信息,以及文檔的網(wǎng)址赋朦。
10.其他
服務(wù)器返回的數(shù)據(jù)格式篓冲,應(yīng)該盡量使用JSON,避免使用XML宠哄。
3.使用Django開(kāi)發(fā)REST接口
我們以在Django框架中使用的圖書(shū)英雄案例來(lái)寫(xiě)一套支持圖書(shū)數(shù)據(jù)增刪改查的REST API接口壹将,來(lái)理解REST API的開(kāi)發(fā)。
在此案例中毛嫉,前后端均發(fā)送JSON格式數(shù)據(jù)诽俯。
views.py
from datetime import datetime
class BooksAPIVIew(View):
"""
查詢所有圖書(shū)、增加圖書(shū)
"""
def get(self, request):
"""
查詢所有圖書(shū)
路由:GET /books/
"""
queryset = BookInfo.objects.all()
book_list = []
for book in queryset:
book_list.append({
'id': book.id,
'btitle': book.btitle,
'bpub_date': book.bpub_date,
'bread': book.bread,
'bcomment': book.bcomment,
'image': book.image.url if book.image else ''
})
return JsonResponse(book_list, safe=False)
def post(self, request):
"""
新增圖書(shū)
路由:POST /books/
"""
json_bytes = request.body
json_str = json_bytes.decode()
book_dict = json.loads(json_str)
# 此處詳細(xì)的校驗(yàn)參數(shù)省略
book = BookInfo.objects.create(
btitle=book_dict.get('btitle'),
bpub_date=datetime.strptime(book_dict.get('bpub_date'), '%Y-%m-%d').date()
)
return JsonResponse({
'id': book.id,
'btitle': book.btitle,
'bpub_date': book.bpub_date,
'bread': book.bread,
'bcomment': book.bcomment,
'image': book.image.url if book.image else ''
}, status=201)
class BookAPIView(View):
def get(self, request, pk):
"""
獲取單個(gè)圖書(shū)信息
路由: GET /books/<pk>/
"""
try:
book = BookInfo.objects.get(pk=pk)
except BookInfo.DoesNotExist:
return HttpResponse(status=404)
return JsonResponse({
'id': book.id,
'btitle': book.btitle,
'bpub_date': book.bpub_date,
'bread': book.bread,
'bcomment': book.bcomment,
'image': book.image.url if book.image else ''
})
def put(self, request, pk):
"""
修改圖書(shū)信息
路由: PUT /books/<pk>
"""
try:
book = BookInfo.objects.get(pk=pk)
except BookInfo.DoesNotExist:
return HttpResponse(status=404)
json_bytes = request.body
json_str = json_bytes.decode()
book_dict = json.loads(json_str)
# 此處詳細(xì)的校驗(yàn)參數(shù)省略
book.btitle = book_dict.get('btitle')
book.bpub_date = datetime.strptime(book_dict.get('bpub_date'), '%Y-%m-%d').date()
book.save()
return JsonResponse({
'id': book.id,
'btitle': book.btitle,
'bpub_date': book.bpub_date,
'bread': book.bread,
'bcomment': book.bcomment,
'image': book.image.url if book.image else ''
})
def delete(self, request, pk):
"""
刪除圖書(shū)
路由: DELETE /books/<pk>/
"""
try:
book = BookInfo.objects.get(pk=pk)
except BookInfo.DoesNotExist:
return HttpResponse(status=404)
book.delete()
return HttpResponse(status=204)
urls.py
urlpatterns = [
url(r'^books/$', views.BooksAPIVIew.as_view()),
url(r'^books/(?P<pk>\d+)/$', views.BookAPIView.as_view())
]
測(cè)試
使用Postman測(cè)試上述接口
1) 獲取所有圖書(shū)數(shù)據(jù)
GET 方式訪問(wèn) http://127.0.0.1:8000/books/承粤, 返回狀態(tài)碼200暴区,數(shù)據(jù)如下
[
{
"id": 1,
"btitle": "射雕英雄傳",
"bpub_date": "1980-05-01",
"bread": 12,
"bcomment": 34,
"image": ""
},
{
"id": 2,
"btitle": "天龍八部",
"bpub_date": "1986-07-24",
"bread": 36,
"bcomment": 40,
"image": ""
},
{
"id": 3,
"btitle": "笑傲江湖",
"bpub_date": "1995-12-24",
"bread": 20,
"bcomment": 80,
"image": ""
},
{
"id": 4,
"btitle": "雪山飛狐",
"bpub_date": "1987-11-11",
"bread": 58,
"bcomment": 24,
"image": ""
},
{
"id": 5,
"btitle": "西游記",
"bpub_date": "1988-01-01",
"bread": 10,
"bcomment": 10,
"image": "booktest/xiyouji.png"
},
{
"id": 6,
"btitle": "水滸傳",
"bpub_date": "1992-01-01",
"bread": 10,
"bcomment": 11,
"image": ""
},
{
"id": 7,
"btitle": "紅樓夢(mèng)",
"bpub_date": "1990-01-01",
"bread": 0,
"bcomment": 0,
"image": ""
}
]
2)獲取單一圖書(shū)數(shù)據(jù)
GET 訪問(wèn) http://127.0.0.1:8000/books/5/ ,返回狀態(tài)碼200辛臊, 數(shù)據(jù)如下
{
"id": 5,
"btitle": "西游記",
"bpub_date": "1988-01-01",
"bread": 10,
"bcomment": 10,
"image": "booktest/xiyouji.png"
}
GET 訪問(wèn)http://127.0.0.1:8000/books/100/仙粱,返回狀態(tài)碼404
3)新增圖書(shū)數(shù)據(jù)
POST 訪問(wèn)http://127.0.0.1:8000/books/,發(fā)送JSON數(shù)據(jù):
{
"btitle": "三國(guó)演義",
"bpub_date": "1990-02-03"
}
返回狀態(tài)碼201彻舰,數(shù)據(jù)如下
{
"id": 8,
"btitle": "三國(guó)演義",
"bpub_date": "1990-02-03",
"bread": 0,
"bcomment": 0,
"image": ""
}
4)修改圖書(shū)數(shù)據(jù)
PUT 訪問(wèn)http://127.0.0.1:8000/books/8/伐割,發(fā)送JSON數(shù)據(jù):
{
"btitle": "三國(guó)演義(第二版)",
"bpub_date": "1990-02-03"
}
返回狀態(tài)碼200,數(shù)據(jù)如下
{
"id": 8,
"btitle": "三國(guó)演義(第二版)",
"bpub_date": "1990-02-03",
"bread": 0,
"bcomment": 0,
"image": ""
}
5)刪除圖書(shū)數(shù)據(jù)
DELETE 訪問(wèn)http://127.0.0.1:8000/books/8/刃唤,返回204狀態(tài)碼
4.明確REST接口開(kāi)發(fā)的核心任務(wù)
在開(kāi)發(fā)REST API接口時(shí)口猜,視圖中做的最主要的三件事:
將請(qǐng)求的數(shù)據(jù)(如JSON格式)轉(zhuǎn)換為模型類(lèi)對(duì)象
操作數(shù)據(jù)庫(kù)
將模型類(lèi)對(duì)象轉(zhuǎn)換為響應(yīng)的數(shù)據(jù)(如JSON格式)
5.序列化 Serialization
我們可以將序列化;理解為:
將程序中的一個(gè)數(shù)據(jù)結(jié)構(gòu)類(lèi)型轉(zhuǎn)換為其他格式(字典透揣、JSON济炎、XML等),例如將Django中的模型類(lèi)對(duì)象轉(zhuǎn)換為JSON字符串辐真,這個(gè)轉(zhuǎn)換過(guò)程我們稱(chēng)為序列化须尚。
如:
queryset = BookInfo.objects.all()
book_list = []
# 序列化
for book in queryset:
book_list.append({
'id': book.id,
'btitle': book.btitle,
'bpub_date': book.bpub_date,
'bread': book.bread,
'bcomment': book.bcomment,
'image': book.image.url if book.image else ''
})
return JsonResponse(book_list, safe=False)
反之崖堤,將其他格式(字典、JSON耐床、XML等)轉(zhuǎn)換為程序中的數(shù)據(jù)密幔,例如將JSON字符串轉(zhuǎn)換為Django中的模型類(lèi)對(duì)象,這個(gè)過(guò)程我們稱(chēng)為反序列化撩轰。
如:
json_bytes = request.body
json_str = json_bytes.decode()
# 反序列化
book_dict = json.loads(json_str)
book = BookInfo.objects.create(
btitle=book_dict.get('btitle'),
bpub_date=datetime.strptime(book_dict.get('bpub_date'), '%Y-%m-%d').date()
)
我們可以看到胯甩,在開(kāi)發(fā)REST API時(shí),視圖中要頻繁的進(jìn)行序列化與反序列化的編寫(xiě)堪嫂。
總結(jié)
在開(kāi)發(fā)REST API接口時(shí)偎箫,我們?cè)谝晥D中需要做的最核心的事是:
將數(shù)據(jù)庫(kù)數(shù)據(jù)序列化為前端所需要的格式,并返回皆串;
將前端發(fā)送的數(shù)據(jù)反序列化為模型類(lèi)對(duì)象淹办,并保存到數(shù)據(jù)庫(kù)中。
-
Django REST framework 簡(jiǎn)介
在序列化與反序列化時(shí)恶复,雖然操作的數(shù)據(jù)不盡相同怜森,但是執(zhí)行的過(guò)程卻是相似的,也就是說(shuō)這部分代碼是可以復(fù)用簡(jiǎn)化編寫(xiě)的谤牡。 開(kāi)發(fā)REST API的視圖中副硅,雖然每個(gè)視圖具體操作的數(shù)據(jù)不同,但增翅萤、刪恐疲、改、查的實(shí)現(xiàn)流程基本套路化断序,所以這部分代碼也是可以復(fù)用簡(jiǎn)化編寫(xiě)的:
增:校驗(yàn)請(qǐng)求數(shù)據(jù) -> 執(zhí)行反序列化過(guò)程 -> 保存數(shù)據(jù)庫(kù) -> 將保存的對(duì)象序列化并返回
刪:判斷要?jiǎng)h除的數(shù)據(jù)是否存在 -> 執(zhí)行數(shù)據(jù)庫(kù)刪除
改:判斷要修改的數(shù)據(jù)是否存在 -> 校驗(yàn)請(qǐng)求的數(shù)據(jù) -> 執(zhí)行反序列化過(guò)程 -> 保存數(shù)據(jù)庫(kù) -> 將保存的對(duì)象序列化并返回
查:查詢數(shù)據(jù)庫(kù) -> 將數(shù)據(jù)序列化并返回
Django REST framework可以幫助我們簡(jiǎn)化上述兩部分的代碼編寫(xiě)流纹,大大提高REST API的開(kāi)發(fā)速度糜烹。
7.認(rèn)識(shí) Django REST framework 框架
Django REST framework 框架是一個(gè)用于構(gòu)建Web API 的強(qiáng)大而又靈活的工具违诗。
通常簡(jiǎn)稱(chēng)為DRF框架 或 REST framework。
DRF框架是建立在Django框架基礎(chǔ)之上疮蹦,由Tom Christie大牛二次開(kāi)發(fā)的開(kāi)源項(xiàng)目诸迟。
特點(diǎn)
提供了定義序列化器Serializer的方法,可以快速根據(jù) Django ORM 或者其它庫(kù)自動(dòng)序列化/反序列化愕乎;
提供了豐富的類(lèi)視圖阵苇、Mixin擴(kuò)展類(lèi),簡(jiǎn)化視圖的編寫(xiě)感论;
豐富的定制層級(jí):函數(shù)視圖绅项、類(lèi)視圖、視圖集合到自動(dòng)生成 API比肄,滿足各種需要快耿;
多種身份認(rèn)證和權(quán)限認(rèn)證方式的支持囊陡;
內(nèi)置了限流系統(tǒng);
直觀的 API web 界面掀亥;
可擴(kuò)展性撞反,插件豐富