-
Notifications
You must be signed in to change notification settings - Fork 0
/
15560194068510.html
469 lines (310 loc) · 13 KB
/
15560194068510.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
<!DOCTYPE html>
<!--[if IEMobile 7 ]><html class="no-js iem7"><![endif]-->
<!--[if lt IE 9]><html class="no-js lte-ie8"><![endif]-->
<!--[if (gt IE 8)|(gt IEMobile 7)|!(IEMobile)|!(IE)]><!--><html class="no-js"><!--<![endif]-->
<head>
<meta charset="utf-8">
<title>
resful 最佳实践 - 搁羽念风
</title>
<meta name="author" content="">
<meta name="description" content="">
<meta name="HandheldFriendly" content="True">
<meta name="MobileOptimized" content="320">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="asset/css/screen.css" media="screen, projection" rel="stylesheet" type="text/css">
<link href="atom.xml" rel="alternate" title="搁羽念风" type="application/atom+xml">
<script src="asset/js/modernizr-2.0.js"></script>
<script src="asset/js/jquery.min.js"></script>
<script src="asset/highlightjs/highlight.pack.js"></script>
<link href="asset/highlightjs/styles/solarized_light.css" media="screen, projection" rel="stylesheet" type="text/css">
<script>hljs.initHighlightingOnLoad();</script>
<style type="text/css">
.cat-children-p{ padding: 6px 0px;}
.hljs{background: none;}
</style>
<script type="text/javascript">
var isAddSildbar = true;
</script>
<script src="asset/js/octopress.js" type="text/javascript"></script>
</head>
<script type="text/javascript">
//链接新开窗口
function addBlankTargetForLinks () {
$('a[href^="http"]').each(function(){
$(this).attr('target', '_blank');
});
}
$(document).ready(function(event) {
addBlankTargetForLinks();
});
</script>
<body >
<header role="banner"><hgroup>
<h1><a href="index.html">搁羽念风</a></h1>
<h2></h2>
</hgroup>
</header>
<nav role="navigation"><ul class="subscription" data-subscription="rss">
<li><a href="atom.xml" rel="subscribe-rss" title="subscribe via RSS">RSS</a></li>
</ul>
<form action="http://google.com/search" method="get">
<fieldset role="search">
<input type="hidden" name="q" value="site:" />
<input class="search" type="text" name="q" results="0" placeholder="Search"/>
</fieldset>
</form>
<ul class="main-navigation">
<li id=""><a target="self" href="index.html">Home</a></li>
<li id=""><a target="_self" href="archives.html">Archives</a></li>
</ul>
</nav>
<div id="main">
<div id="content">
<div>
<article class="hentry" role="article">
<header>
<h1 class="entry-title">resful 最佳实践</h1>
<p class="meta"><time datetime="2019-04-23T19:36:46+08:00" pubdate data-updated="true">2019/4/23</time></p>
</header>
<div class="entry-content">
<h2 id="toc_0">url设计</h2>
<ol>
<li>推荐使用复数名词 <code>/employees/21</code></li>
<li>在资源集合URL 上使用GET方法,更加直观 <code>GET /employees?state=external</code></li>
<li>对特定资源进行过滤, 将搜索字符串附加到查询参数中即可 <code>GET /employees?state=internal</code></li>
</ol>
<h2 id="toc_1">使用http方法操作资源(CURD)</h2>
<blockquote>
<p>这种方式可以用简洁的方式获取7种操作资源的方式<br/>
如果一个请求是 indempotent(即发送两个一样的请求,后一个会覆盖前一个),此时使用PUT方法,否则使用POST方法</p>
</blockquote>
<table>
<thead>
<tr>
<th></th>
<th>Post(创建)</th>
<th>GET(读取)</th>
<th>PUT(更新)</th>
<th>DELETE(删除)</th>
</tr>
</thead>
<tbody>
<tr>
<td>/employees</td>
<td>创建</td>
<td>列出</td>
<td>批量更新</td>
<td>删除所有</td>
</tr>
<tr>
<td>/employees/56</td>
<td>X</td>
<td>获取56号员工的信息</td>
<td>更新56号员工的信息</td>
<td>删除56号员工的信息</td>
</tr>
</tbody>
</table>
<h2 id="toc_2">非资源请求用动词</h2>
<blockquote>
<p>使用动词来区分资源和非资源,url中使用动词而非名词 <code>GET /translate?from=de_DE&to=en_US&text=Hallo</code><br/>
增加资源动作控制参数 <code>PUT /articles/id?published=true</code><br/>
把动作转换为一个可以操作的资源 例如github,"喜欢"一个gist,转换为增加一个<code>/gists/id/star</code>子资源,对其操作 <code>PUT /gists/id/star</code>,<code>DELETE /gists/:id/star</code></p>
</blockquote>
<h2 id="toc_3">使用标准 http 响应码</h2>
<h3 id="toc_4">请求成功:</h3>
<ul>
<li>200 OK: 请求已成功,Body有返回内容, 用于 GET Method 的API 返回码</li>
<li>201 Created: 请求已经被实现,资源被创建. 用于 POST Method的同步类型API返回码</li>
<li>202 Accepted: 服务器已经接受请求,但尚未处理. 用于 POST Method的异步类型API返回码</li>
<li>204 No Content: 服务器成功处理了请求,但没有返回任何内容, 用于 DELETE/PUT Method 的API的返回码</li>
</ul>
<h3 id="toc_5">因为客户端原因导致请求失败:</h3>
<ul>
<li>400 Bad Request: 如参数错误,格式错误</li>
<li>401 Unauthorized: 用户未被认证, 如果密码错误,证书错误</li>
<li>403 Forbidden: 用户权限不够</li>
<li>404 Not Found: 服务器无此资源, 通常为URL不存在,或者某个Method不存在</li>
<li>409 Conflict: 请求存在冲突,无法处理该请求 (比如某个资源禁止被再次修改,但请求想修改该资源,就要返回409)</li>
</ul>
<h3 id="toc_6">因服务端原因导致请求失败:</h3>
<ul>
<li>500 Internal Server Error: 服务端错误消息,服务器遇到一个未曾预料的状况</li>
<li>501 Not Implemented: 服务器不支持当前请求所需要的某个功能</li>
<li>503 Service Unavailable: 如服务器维护中或者过载等</li>
</ul>
<h2 id="toc_7">返回有用的提示信息</h2>
<h3 id="toc_8">除了合适的状态码之外,还应当在正文中提供有用的错误提示和详细的描述</h3>
<pre class="line-numbers"><code class="language-javascript"> // 400 Bad Request
{
"message": "You submitted an invalid state. Valid state values are 'internal' or 'external'",
"errorCode": 352,
"additionalInformation" :"http://www.domain.com/rest/errorcode/352"
}
</code></pre>
<h3 id="toc_9">响应中提供浏览其他API的链接</h3>
<blockquote>
<p>如,在响应参数中添加一个 links 字段，让客户端可以自动变更,也可以自我描述,需要提供的文档更少</p>
</blockquote>
<pre class="line-numbers"><code class="language-javascript">{
"id":1,
"name":"Paul",
"links": [
{
"rel": "salary",
"href": "/employees/1/salaryStatements"
}
]
}
</code></pre>
<h3 id="toc_10">提供分页信息</h3>
<blockquote>
<p>资源较多时,可以用 <code>page</code>,<code>page_size</code> 来提供分页 <code>/employees?page=30&page_size=15 #返回 30 到 45 的员工</code><br/>
还可以添加上一页和下一页的链接示例</p>
</blockquote>
<pre class="line-numbers"><code class="language-text"> GET /employees?offset=20&limit=10
{
"offset": 20,
"limit": 10,
"total": 3465,
"employees": [
//...
],
"links": [
{
"rel": "nextPage",
"href": "/employees?offset=30&limit=10"
},
{
"rel": "previousPage",
"href": "/employees?offset=10&limit=10"
}
]
}
</code></pre>
<h2 id="toc_11">使用https</h2>
<blockquote>
<p>禁止非ssl的url重定向到ssl的url</p>
</blockquote>
<h2 id="toc_12">授权</h2>
<ul>
<li>验证(Authentication) 为了确定用户申明的身份</li>
<li>授权(Authorization) 为用户增加某个资源的操作权限</li>
</ul>
<h2 id="toc_13">Location</h2>
<p>在响应的header中使用,一般为客户端感兴趣的资源url,如果成功创建一个资源后,把新资源url放在Location中<br/>
异步创建请求,也可以在响应 202的同时,添加一个可以异步状态查询的地址</p>
<h2 id="toc_14">API地址</h2>
<p>在url中指定API的版本号 <code>https://api.github.com/v3</code><br/>
如果api变化很大,可以把api设计为子域名 <code>https://v3.api.demo.com</code><br/>
不需要次级版本,只有当接口不兼容,才应该变更版本号</p>
<h3 id="toc_15">两种实现方式</h3>
<ul>
<li> url中 如<code>https://example.com/api/v1</code>,
<ul>
<li>版本明确,方便调试</li>
<li>不同版本协议解析可以放在不同的服务器上</li>
<li>不用考虑协议兼容性,开发简便,升级不受影响</li>
</ul></li>
<li>HTTP Header 中
<ul>
<li>url简洁干净,符合RESTful惯例</li>
</ul></li>
</ul>
<h2 id="toc_16">连字符</h2>
<p>url 中应该尽量使用 "-" 来代替下划线"_"的使用,如<br/>
<code>http://api.example.restapi.org/blogs/mark-masse/entries/this-is-my-first-post</code></p>
<h2 id="toc_17">大小写</h2>
<p>根据 RFC3986 定义，URI 是对大小写敏感的，所以为了避免歧义，我们尽量用小写字符</p>
</div>
<footer>
<p class="meta">
<strong>Categories:</strong>
<span class="categories">
<a class='category' href='%E8%AE%BE%E8%AE%A1%E6%A8%A1%E5%BC%8F.html'>设计模式</a>
</span>
</p>
<p class="meta">
</p>
<div class="sharing">
</div>
<p class="meta">
<a class="basic-alignment left" href="15560743380263.html"
title="Previous Post: 深度思维笔记">« 深度思维笔记</a>
<a class="basic-alignment right" href="15554074466566.html"
title="Next Post: git 一些常用的命令">git 一些常用的命令 »</a>
</p>
</footer>
</article>
</div>
<aside class="sidebar">
<section>
<h1>Categories</h1>
<ul id="recent_posts">
<li class="post">
<a href="linux.html"><strong>linux (3)</strong></a>
</li>
<li class="post">
<a href="%E6%95%B0%E6%8D%AE%E5%BA%93.html"><strong>数据库 (6)</strong></a>
<p class="cat-children-p">
<a href="redis.html">redis (3)</a>
<a href="clickhouse.html">clickhouse (3)</a>
</p>
</li>
<li class="post">
<a href="%E4%B8%AD%E9%97%B4%E4%BB%B6.html"><strong>中间件 (6)</strong></a>
<p class="cat-children-p">
<a href="%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97.html">消息队列 (4)</a>
<a href="%E6%95%B0%E6%8D%AE%E6%B8%85%E6%B4%97.html">数据清洗 (1)</a>
<a href="%E7%9B%91%E6%8E%A7%E6%8A%A5%E8%AD%A6.html">监控报警 (1)</a>
</p>
</li>
<li class="post">
<a href="%E8%AF%AD%E8%A8%80.html"><strong>语言 (9)</strong></a>
<p class="cat-children-p">
<a href="lua.html">lua (1)</a>
<a href="php.html">php (4)</a>
<a href="golang.html">golang (4)</a>
</p>
</li>
<li class="post">
<a href="%E5%B7%A5%E5%85%B7.html"><strong>工具 (2)</strong></a>
</li>
<li class="post">
<a href="%E8%AE%BE%E8%AE%A1%E6%A8%A1%E5%BC%8F.html"><strong>设计模式 (3)</strong></a>
</li>
<li class="post">
<a href="%E8%AF%BB%E4%B9%A6%E7%AC%94%E8%AE%B0.html"><strong>读书笔记 (1)</strong></a>
</li>
</ul>
</section>
<section>
<h1>Recent Posts</h1>
<ul id="recent_posts">
<li class="post">
<a href="15589244025963.html">大数据架构</a>
</li>
<li class="post">
<a href="15586915631306.html">对lua携程做超时时间</a>
</li>
<li class="post">
<a href="15586915348117.html"></a>
</li>
<li class="post">
<a href="15586818694083.html">nsq简介</a>
</li>
<li class="post">
<a href="15585794233066.html">mac 安装nsq</a>
</li>
</ul>
</section>
</aside> </div></div>
<footer role="contentinfo"><p>
Copyright © 2014 - -
<span class="credit">Powered by <a target="_blank" href="http://www.mweb.im">MWeb</a> Theme by <a href="http://octopress.org">Octopress</a></span>
</p>
</footer>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script><script type="text/x-mathjax-config">MathJax.Hub.Config({TeX: { equationNumbers: { autoNumber: "AMS" } }});</script>
</body>
</html>