我们知道 URL 后面的 query string 实际上是一个字典的形式。URL 的任何一个规范中都没有定义如何在 query 中传递数组，但是这个需求也是实际存在的，于是就诞生各种奇葩的形式，本文做一个总结。

常见的形式

http://www.baidu.com/search?q=url&tag=foo

这是一个正常的 URL，这里解析出来应该是一个字典 {"q": "url", "foo": "bar"}。但是 Python 会强行解析成数组 {"q": ["url"], "tag": ["foo"]}。

使用 URL 表示数组有以下几种常见形式：

http://www.baidu.com/search?q=url&tag=foo&tag=bar

重复键表示数组，Python/Node 中可以正确解析成数组，Java 只读取第一个值，PHP 只读取最后一个值。

http://www.baidu.com/search?q=url&tag[]=foo&tag[]=bar

键后增加[]并重复表示数组。PHP/Node 可以解析为 tag=[foo, bar]。Python 会解析成

PHP 的 http_build_query 会生成这种格式。

In [6]: from urllib.parse import parse_qs

In [7]: parse_qs("tag=foo&tag=bar")
Out[7]: {'tag': ['foo', 'bar']}

In [8]: parse_qs("tag[]=foo&tag[]=bar")
Out[8]: {'tag[]': ['foo', 'bar']}

In [9]: parse_qs("tag=foo")
Out[9]: {'tag': ['foo']}

http://www.baidu.com/search?q=url&tag[0]=foo&tag[1]=bar

使用数组形式表示。貌似没有原因能够处理，但是用的还挺多的。

http://www.baidu.com/search?q=url&tag=foo,bar

使用逗号分隔。貌似没有语言默认会处理这种，需要自己手工处理。但是我最喜欢这种。

一个更奇葩的例子

https://www.doi.gov/careers/explore-careers?f[0]=bureaus:20&f[1]=competencies:1638&f[2]=competencies:1642&f[3]=competencies:1648&f[4]=competencies:1656&f[5]=competencies:1661&f[6]=gs_levels:17&f[7]=gs_levels:158

总之，在不同的语言中，乃至于不同的 web 框架中对以上形式有不同的解析，非常混乱。

参考资料

1. https://stackoverflow.com/questions/6243051/how-to-pass-an-array-within-a-query-string
2. https://stackoverflow.com/questions/11889997/how-to-send-an-array-in-url-request/11890080
3. https://stackoverflow.com/questions/1763508/passing-arrays-as-url-parameter
4. https://stackoverflow.com/questions/1746507/authoritative-position-of-duplicate-http-get-query-keys

今天有个项目需要用到 OAuth2 来处理一些东西，然而中文互联网有时候真是很难找到像样的文档，搜索 “OAuth 教程” 的到排名前两位的[教](https://aaronparecki.com/oauth-2-simplified/)[程](https://aaronparecki.com/oauth-2-simplified/)都是翻译自一个英文教程，翻译质量奇差无比就不说了，这个英文教程本身就是有问题的，无奈只好搜索 “OAuth tutorial” 才找到几个看得过去的英文教程，总结一下放在这里，算是为中文互联网引入一些正确的知识。

看到 OAuth2 这个词，一般人肯定会想，是不是还有个 OAuth 1 协议呢？是的，有 OAuth 1 协议，但是因为协议搞得太复杂了，所以没人用，市面上的基本都是根据 OAuth 2 来的。既然实际只有一个 OAuth，以下就简称 OAuth 了。

# 为什么要使用 OAuth —— 一个例子

大家最熟悉的例子就是第三方登录了。假设有个论坛叫做“91论坛”你没有注册过，也懒得填写邮箱，然后验证邮箱注册，那么这时候可以使用 QQ 登录，当然国外可能是 Facebook。那么问题来了，当你点击 “用 QQ 登录” 这个按钮的时候，论坛怎么安全地知道你使用的是哪个 QQ 号呢？会有下面几个问题：

1. 如果你随便输入一个 QQ 号，然后91论坛就信任了，那么你就可以伪造任意的 QQ 用户了，所以论坛需要去向 QQ 验证你是否是你提供的 QQ 号的所有者。
2. 你可以提供给论坛你的 QQ 号和密码，这样论坛使用你的 QQ 号和密码测试一下能否登录就可以了，但是这样论坛就有了你QQ号的所有权限，如果论坛偷偷在你的 QQ 空间发推广消息呢？所以你不希望直接把 QQ 号和密码都告诉论坛。
3. 现在陷入了两难境界，论坛无法信任你只提供 QQ 号，你也不能信任论坛拿走你的账户密码。如果这时候能让 QQ 作为中间人只提供给论坛部分信息就好了，OAuth 就是用来做这个的。

# OAuth2

简单来说，方案如下：

1. 91 论坛在QQ上注册一个app
2. 用户在QQ上登录，通过跳转，把一个一次性授权码给 91 论坛
3. 论坛利用这个授权码获得 access token，然后利用这个 token 读取用户信息

具体解决方案如下：

1. 91论坛的开发者在 QQ 处申请一个开发者账户，获得一个开发者标识，并提供了一个回调接口：

“`
{
‘client_id’: 91bbs,
‘client_secret’: 123456,
‘callback’: “http://91bbs.com/login_callback”
}
“`

2. 你在91论坛上点击用 QQ 登录，然后页面跳转到 QQ 域(qq.com)下，这样你可以安全的输入 QQ 密码，而不用被91论坛知道。

用 QQ 登录对应的地址：

“`
https://api.qq.com/v1/auth?
response_type=code&
client_id=91bbs&
callback=http://91bbs.com/login_callback&
scope=read
“`

注意其中标识了论坛在上一步 client_id。在这个页面上可能写着你是否授权XX论坛访问你的个人信息等等。

1. response_type 表示授权的类型，后面会讲到
2. client_id 向 QQ 表明是要登录91论坛这个网站
3. callback 指明了下一步QQ要回调91论坛的地址
4. scope 指定了当前授权的权限范围

3. 登录QQ后，点击授权通过，然后 QQ 会把你重定向到 redirect_uri 对应的页面，并附加参数 code=xxx，这个是一个临时的一次性授权码。

重定向到的页面：

“`
http://91bbs.com/login_callback&code=xxxxxx
“`

4. 访问这个页面，就会把这个 code 传递给91论坛，但是91论坛有了这个 code 还不能直接向 QQ 询问关于你的具体信息。
5. 91论坛使用这个 code 向 QQ 申请一个 access token，使用这个 access token 就可以获取你的 QQ 号等信息，具体获得什么信息，是在第二步的 scope 页面指定的。

访问：
“`
POST https://api.qq.com/v1/token
grant_type=authorization_code&
code=AUTH_CODE_HERE&
redirect_uri=REDIRECT_URI&
client_id=CLIENT_ID&
client_secret=CLIENT_SECRET
“`

注意其中的参数：
1. grant_type 指定了授权的类型，这里我们使用上一步获得的 authorization code 来获取 access token，所以grant type 就是 authorization code
2. code 就是上一步获得的 authorization code
3. 其他参数和上一步类似

QQ 返回给 91 论坛的信息：
“`
{
“access_token”:”ACCESS_TOKEN”,
“token_type”:”bearer”,
“expires_in”:2592000,
“refresh_token”:”REFRESH_TOKEN”,
“scope”:”read”,
}
“`

因为这个 access token 可以随时用来访问你的信息，所以设定了过期时间，这样即使泄露了攻击的时间窗口也不会很长。

6. 91论坛使用 access token 访问你的信息。access token 通常是放在 [Authorization](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) 这个 header 中。

比如使用 curl 来表示这个访问：

“`
curl -H ‘Authorization: Bearer 1.1Zgwxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=’ \
‘http://api.qq.com/v1/user/123456’
“`

如果 token 正确无误的话，QQ 服务器会返回相应的信息。

6. 论坛根据从 QQ 服务器得到的消息，从而知道你真的是 QQ 为 123456 的用户，然后为你创建账户。以后你需要登录也可以重复上面的流程，证明你的确是 QQ 123456 的用户就可以了。

# OAuth 中的术语

在上面的过程中，一共出现了四中角色：

1. 第三方程序，也就是 91论坛
2. 资源所有人，也就是用户
3. 授权服务器，也就是 QQ
4. 资源服务器，还是 QQ

其中资源指的就是用户的 QQ 信息，而授权服务器和资源服务器在复杂的结构中往往是分开的。

# 其他的授权类型

除了上面说过授权类型之外，还有一些微小差异的授权类型，比如 implict 授权，这里不再赘述。

除此之外，还可以直接使用账户密码获得 access token，方法比较简单，一般用于官方客户端直接登录：

“`
POST https://api.authorization-server.com/token
grant_type=password&
username=USERNAME&
password=PASSWORD&
client_id=CLIENT_ID
“`

当 access token 过期后，还可以使用 refresh token 刷新，获得新的有效的 access token，而不需要用户再次登录。虽然 refresh token 没有过期时间，或者过期时间远比 access token 长，但是因为使用次数少，所以也是相对比较安全的。

“`
POST https://cloud.digitalocean.com/v1/oauth/token?
grant_type=refresh_token&
client_id=CLIENT_ID&
client_secret=CLIENT_SECRET&
refresh_token=REFRESH_TOKEN
“`

# 参考

1. [OAuth2 Simplified](https://aaronparecki.com/oauth-2-simplified/)
2. [Introduction to OAuth2](https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2)
3. [Refresh token](https://medium.com/@bantic/more-oauth-2-0-surprises-the-refresh-token-1831d71f4af6)

HTTP 中常用的方法有 GET/POST/PUT/DELETE 等，在设计API或者表单的时候我们需要选择合适的方法。一般有两种方案：

1. 只使用 GET 和 POST，GET 主要用来读取数据，POST 用来创建或者更新数据。
2. RESTful的方法，GET/POST/PUT/DELETE 分别用来增删改查。

# URL 的设计

为了探讨两种方案，首先我们来看一下 URL 的设计。URL 是 Universal Resource Locator 的缩写，也就是一个 URL 表示的是唯一的一个资源，所以这个资源的 id 或者说主键应该是放在 URL 路径中的。

比如一个好的设计：

“`
http://example.com/post/1234
“`

不好的设计

“`
http://example.com/post?id=1234
“`

而控制这个资源展示方式的其他字段可以作为参数：

“`
http://exmaple.com/post/1234?lang=zh&utm_source=google
“`

# HTTP 方法的含义

好多人对于 http 方法的理解是 GET 是参数在url里，而POST是参数在 body 里面，这样理解是不对的。

在上述的两种方案中，GET 都是用来读取资源的，一般来说不要对资源进行任何更新操作，也就是没有副作用。比如说

不好的设计：
“`
GET http://example.com/post/1234?action=delete
“`

上面的设计意图通过GET操作来删除一个资源，这样非常不好。比如说如果浏览器具有预缓存页面的功能，那么预先读取这个链接的时候就把对应的资源删掉了。

一般来说，GET 方法还要求幂等性，也就是无论多少次操作，最终结果和操作一次都是一样的。GET 操作的参数受到 url 长度的限制，当参数超过 1k 的时候，可以使用 POST 代替。不过这时候你首先应该想一下这么多参数是不是都有用，是不是设计有问题。

POST 方法可以用来创建资源，比如说：

“`
POST http://example.com/post/

content=xxxxxxx&author=xxxx&date=xxxx
“`

POST 操作具有副作用，也就是说会更改服务器上的状态。另外 POST 操作一般不是幂等的，每次 POST 操作都应该创建一个新的资源。

PUT 操作用来更新资源，也是幂等的。

“`
PUT http://example.com/post/1234

content=yyyyyy
“`

DELETE 用来删除资源，值得注意的是，根据规范 DELETE 方法不能带有 body。

“`
DELETE http://example.com/post/1234
“`

周末给一个库添加http代理的支持，发现对http basic auth不甚了解，阅读了一下相关的文档，写篇备忘。

http 中的认证主要是 basic auth 和 digest auth 两种，其中 digest auth 比较复杂，而且也没有提升安全性，已经不建议使用了。

RFC 7235 [1] 描述了客户端（通常是浏览器）和服务器如何通过http进行身份认证的一些机制。客户端和 http代理之间也可以使用 http auth 来做验证。
 
# 验证流程

1. 当客户端访问一个页面时，如果只有验证后才能访问，或者验证后有更多内容，服务器应该发送 401 Unauthorized，提出一个chanllenge，设定 `WWW-Authenticate` header，并指定验证的 type 和 realm，具体定义下文有讲。
2. 客户端这时通常应该提示用户输入密钥，一般是浏览器弹出用户名密码对话框供用户填写，然后使用`Authorization` header发送验证的密钥。如果验证通过的话，应该正常访问（200 OK），验证通过但是没有权限的话应该返回 403 Forbidden。
3. 如果验证不通过，应该服务器返回401，客户端可以重试。

注意，如果客户端已经知道需要密钥访问，那么可以在第一个请求直接发送对应的密钥，这样就避免了 401 Unauthorized。

 

# 代理验证的不同

如果代理服务器需要验证的话，流程是类似的，有两点细节不同：

1. 代理服务器应该发送407 Proxy Authentication Required 而不是 401。使用的headers也变成了 Proxy-Authenticate 和 Proxy-Authorization 。
2. 服务器的头部 WWW-Authenticate 是 end-to-end 的，也就是代理服务器不应该篡改，应该原样传递。而代理服务器的Proxy-头部是 hop-by-hop 的，也就是不能向下传递。

# 实现细节

服务器或者代理服务器随着4XX发送的头部为

“`
WWW-Authenticate: <type> realm=<realm>
or
Proxy-Authenticate: <type> realm=<realm>
“`

其中 type 指定了使用的验证的类型，也就是用户名和密码加密方式的不同，IANA钦定了一批方法[2]。然鹅，一般来说常用的只有两个 Basic 和 Digest。而其中 Digest 的实现可能会要求服务器明文存储密码，于是大家又angry了[3]，这里也不推荐使用。所以这里只介绍 Basic类型。

realm 指定了验证的领域，也就是说相同realm下的用户名和密码是一样的，如果你访问的两个页面在同一个realm，那么浏览器在第二次访问就不会问你密码了。

客户端发送对应的头部和密钥来获得访问权限

“`
Authorization: <type> <credentials>
or
Proxy-Authorization: <type> <credentials>
“`

其中，type就是刚刚的那个 Basic 或者 Digest。credentials 按照对应的方法计算。对于Basic类型 `credentials = base64(username + ‘:’ + password)`

一个例子，假设用户名和密码分别是：aladdin和opensesame。那么客户端应该发送的header是：`Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l`

# 需要注意的地方

1. 因为http协议本身是无状态的，所以Auth应该是无状态的，所以每次请求都应该携带。
 
2. 如果是http协议的话，对于Basic Auth，那么密码都是明文发送的，可以使用https来避免这个问题。

3. 可以使用：https://username:password@www.example.com/ 这种形式来预先输入账号密码，但是这种形式已经不鼓励了。不过在设定一些环境变量时，比如 http_proxy，也只能用这种方法来制定用户名和密码

参考：

1. 对应的RFC https://tools.ietf.org/html/rfc7235
2. IANA 注册的auth类型 http://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml
3. 为什么不要使用digest验证  https://stackoverflow.com/questions/2384230/what-is-digest-authentication
4. MDN的文章还提供了如何让apache和nginx使用basic auth https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication

和缓存相关的 header 共有如下几种

* `Pragma`
* `Cache-Control`
* `Expires`
* `Last-Modified`
* `Etag`
* `If-Modified-Since`
* `If-Non-Match`

Expires 由服务器返回，用于指定当前页面过期时间，使用绝对时间表示。

Cache-Control 指定了相对过期的时间，由当前时间多久后过期的秒数表示。

“`
Cache-Control: max-age=86400
“`

Last-Modified 是由服务器给出了文档的过期时间，当第二次请求该文档的时候，浏览器可以使用 If-Modified-Since 头部指定该过期时间，如果文档还没有过期，那么服务器应该返回 304，否则返回 200 和新文档。

Etag 是由服务器给出的文档的哈希值，当第二次请求该文档的时候，浏览器可以使用 If-None-Match 头部指定该哈希值，如果文档没有变动，那么服务器应该返回 304，如果有变动，那么哈希值也变了，应该返回 200 和新文档。

可以看出 Etag 相比 Last-Modified 更准确一些，所以两个头部都有的前提下，应该是 Etag 优先。

实际使用中，为了兼容性考虑，应该把这几种头部都结合起来使用。

see:

1. https://www.mnot.net/cache_docs/
2. http://stackoverflow.com/questions/499966/etag-vs-header-expires