any获取用户授权页面url
+注意：如果用户已关注公众号，且从公众号的会话或自定义菜单中进入授权页，即使是snsapi_userinfo，也是静默授权的！
Promise获取访问Token
+此步骤可以获取到用户的openid
+Promise刷新token
+由于access_token有效期较短，如果授权方式为 snsapi_userinfo，且想长期静默获取用户的信息，需要定期刷新token，以维持access_token与refresh_token的有效性。
+备注：
+Promise拉取用户详细
+仅限授权作用域为 snsapi_userinfo 有效。
Promise校验授权凭证是否有效
+如果授权作用域为 snsapi_userinfo，则拉取用户详细信息前可以先检查授权凭证是否有效。
+如果授权凭证已失效，可调用刷新凭证。
any
+获取用户授权页面url
+
+注意：如果用户已关注公众号，且从公众号的会话或自定义菜单中进入授权页，即使是`snsapi_userinfo`，也是静默授权的！
+
+**Kind**: global function
+**Returns**: any - 成功则返回拼装结果，失败返回`false`
+
+```javascript
+{
+ url: string,
+ state: string,
+}
+```
+
+字段 | 描述
+----- | -----
+url | 拼装完成的授权url，用户在微信中打开后进入授权流程
+state | 本次请求的访问标识，用于区分不同用户
+
+| Param | Type | Description |
+| --- | --- | --- |
+| appid | string | 公众号appid |
+| redirect_uri | string | 授权回调页面url |
+| state | string | 访问标识，用于区分不同的用户。 【可省略】默认生成uuid |
+| scope | string | 用户授权作用域 授权类型： - snsapi_base 静默授权，不弹授权页面，直接跳转，仅获得openid - snsapi_userinfo 显式授权，弹出授权页面，获得用户更多信息 【可省略】默认使用静默授权 |
+
+
+
+## getToken(appid, r_url, secret) ⇒ Promise
+获取访问Token
+
+此步骤可以获取到用户的openid
+
+**Kind**: global function
+**Returns**: Promise - 返回一个Promise
+请求成功则Promise会返回一个Object如下：
+
+```javascript
+{
+ access_token: 'ACCESS_TOKEN',
+ expires_in: 7200,
+ refresh_token: 'REFRESH_TOKEN',
+ openid: 'OPENID',
+ scope: 'SCOPE',
+ state: string
+}
+```
+
+字段 | 描述
+------------- | -------------
+access_token | 网页授权接口调用凭证,注意：此access_token与基础支持的access_token不同
+expires_in | access_token接口调用凭证超时时间，单位（秒）
+refresh_token | 刷新凭证
+openid | 用户唯一标识，请注意，在未关注公众号时，用户访问公众号的网页，也会产生一个用户和公众号唯一的OpenID
+scope | 用户授权的作用域，使用逗号（,）分隔
+state | 本次访问请求标识
+
+| Param | Type | Description |
+| --- | --- | --- |
+| appid | string | 公众号appid |
+| r_url | string | 可提供两种参数： - url 被请求的授权回调页面完整url，会自动提取code与state - code 从授权回调请求参数中提取的code参数 |
+| secret | string | 公众号的appsecret |
+
+
+
+## refreshToken(appid, refresh_token) ⇒ Promise
+刷新token
+
+由于access_token有效期较短，如果授权方式为 snsapi_userinfo，且想长期静默获取用户的信息，需要定期刷新token，以维持access_token与refresh_token的有效性。
+
+备注：
+- access_token 有效期为 7200秒
+- refresh_token 有效期为 30天
+
+**Kind**: global function
+**Returns**: Promise - 返回一个Promise
+请求成功则Promise会返回一个Object如下：
+
+```javascript
+{
+ access_token: 'ACCESS_TOKEN',
+ expires_in: 7200,
+ refresh_token: 'REFRESH_TOKEN',
+ openid: 'OPENID',
+ scope: 'SCOPE',
+}
+```
+
+字段 | 描述
+------------- | -------------
+access_token | 网页授权接口调用凭证,注意：此access_token与基础支持的access_token不同
+expires_in | access_token接口调用凭证超时时间，单位（秒）
+refresh_token | 刷新凭证
+openid | 用户唯一标识，请注意，在未关注公众号时，用户访问公众号的网页，也会产生一个用户和公众号唯一的OpenID
+scope | 用户授权的作用域，使用逗号（,）分隔
+
+| Param | Type | Description |
+| --- | --- | --- |
+| appid | string | 公众号appid |
+| refresh_token | string | 刷新凭证 |
+
+
+
+## getUserinfo(access_token, openid, lang) ⇒ Promise
+拉取用户详细
+
+仅限授权作用域为 `snsapi_userinfo` 有效。
+
+**Kind**: global function
+**Returns**: Promise - 返回一个Promise
+请求成功则Promise会返回一个Object如下：
+
+```javascript
+{
+ openid: 'OPENID',
+ nickname: 'NICKNAME',
+ sex: '1',
+ province: 'PROVINCE',
+ city: 'CITY',
+ country: 'COUNTRY',
+ headimgurl: 'http://wx.qlogo.cn/mmopen/g3MonUZtNHkdmzicIlibx6iaFqAc56vxLSUfpb6n5WKSYVY0ChQKkiaJSgQ1dZuTOgvLLrhJbERQQ4eMsv84eavHiaiceqxibJxCfHe/46',
+ privilege: ['PRIVILEGE1', 'PRIVILEGE2'],
+ unionid: 'o6_bmasdasdsad6_2sgVt7hMZOPfL',
+}
+```
+
+字段 | 描述
+---------- | ---------
+openid | 用户的唯一标识
+nickname | 用户昵称
+sex | 用户的性别，值为1时是男性，值为2时是女性，值为0时是未知
+province | 用户个人资料填写的省份
+city | 普通用户个人资料填写的城市
+country | 国家，如中国为CN
+headimgurl | 用户头像，最后一个数值代表正方形头像大小（有0、46、64、96、132数值可选，0代表640*640正方形头像），用户没有头像时该项为空。若用户更换头像，原有头像URL将失效。
+privilege | 用户特权信息，json 数组，如微信沃卡用户为（chinaunicom）
+unionid | 只有在用户将公众号绑定到微信开放平台帐号后，才会出现该字段。
+
+| Param | Type | Description |
+| --- | --- | --- |
+| access_token | string | 网页授权接口调用凭证 |
+| openid | string | 用户openid |
+| lang | string | 返回信息的语言版本 【可省略】默认为 简体中文 - zh_CN 简体中文 - zh_TW 繁体中文 - en 英语 |
+
+
+
+## checkAccessToken(access_token, openid) ⇒ Promise
+校验授权凭证是否有效
+
+如果授权作用域为 `snsapi_userinfo`，则拉取用户详细信息前可以先检查授权凭证是否有效。
+如果授权凭证已失效，可调用刷新凭证。
+
+**Kind**: global function
+**Returns**: Promise - 返回一个Promise
+请求成功则Promise返回一个boolean值，如果是true则凭证有效
+
+| Param | Type | Description |
+| --- | --- | --- |
+| access_token | string | 网页授权接口调用凭证 |
+| openid | string | 用户openid |
+
diff --git a/README.md b/README.md
index 51fa489..1db6e1d 100644
--- a/README.md
+++ b/README.md
@@ -2,14 +2,10 @@
封装微信公众平台的网页授权逻辑，简化开发网页授权的步骤。
-## 使用
+## 调用
+
+点击查看 [API文档](API.md)
+
-提供以下方法：
-- getAuthUrl()
-- getToken()
-- getUserinfo()
-- refreshToken()
-- checkAccessToken()
-## 其他
diff --git a/index.js b/index.js
index d42df75..c7c67a3 100644
--- a/index.js
+++ b/index.js
@@ -11,6 +11,14 @@ const uuid = require('uuid')
const request = require('request')
+/**
+ * 检查url是否合法
+ *
+ * @param {string} url 要检查的url
+ * @returns {boolean} 是否为合法url
+ * @ignore
+ */
+
function checkUrl(url) {
return /^(http|https):\/\//.test(url)
}
@@ -30,16 +38,20 @@ function checkUrl(url) {
* - snsapi_base 静默授权，不弹授权页面，直接跳转，仅获得openid
* - snsapi_userinfo 显式授权，弹出授权页面，获得用户更多信息
* 【可省略】默认使用静默授权
- * @returns {any} 返回拼装结果
+ * @returns {any} 成功则返回拼装结果，失败返回`false`
+ *
+ * ```javascript
* {
* url: string,
* state: string,
* }
+ * ```
*
- * 参数 | 描述
+ * 字段 | 描述
* ----- | -----
* url | 拼装完成的授权url，用户在微信中打开后进入授权流程
* state | 本次请求的访问标识，用于区分不同用户
+ *
*/
function getAuthUrl(appid, redirect_uri, state, scope) {
@@ -69,6 +81,8 @@ function getAuthUrl(appid, redirect_uri, state, scope) {
* @param {string} secret 公众号的appsecret
* @returns {Promise} 返回一个Promise
* 请求成功则Promise会返回一个Object如下：
+ *
+ * ```javascript
* {
* access_token: 'ACCESS_TOKEN',
* expires_in: 7200,
@@ -77,12 +91,13 @@ function getAuthUrl(appid, redirect_uri, state, scope) {
* scope: 'SCOPE',
* state: string
* }
+ * ```
*
- * 参数 | 描述
+ * 字段 | 描述
* ------------- | -------------
* access_token | 网页授权接口调用凭证,注意：此access_token与基础支持的access_token不同
* expires_in | access_token接口调用凭证超时时间，单位（秒）
- * refresh_token | 用户刷新access_token
+ * refresh_token | 刷新凭证
* openid | 用户唯一标识，请注意，在未关注公众号时，用户访问公众号的网页，也会产生一个用户和公众号唯一的OpenID
* scope | 用户授权的作用域，使用逗号（,）分隔
* state | 本次访问请求标识
@@ -136,30 +151,35 @@ function getToken(appid, r_url, secret) {
/**
* 刷新token
*
- * 由于access_token有效期较短，如果授权方式为 snsapi_userinfo，且想长期静默获取用户的信息，需要定期刷新token，以维持access_token与refresh_token的有效性
+ * 由于access_token有效期较短，如果授权方式为 snsapi_userinfo，且想长期静默获取用户的信息，需要定期刷新token，以维持access_token与refresh_token的有效性。
+ *
* 备注：
* - access_token 有效期为 7200秒
* - refresh_token 有效期为 30天
*
- * @param {string} appid
- * @param {string} refresh_token
+ * @param {string} appid 公众号appid
+ * @param {string} refresh_token 刷新凭证
* @returns {Promise} 返回一个Promise
* 请求成功则Promise会返回一个Object如下：
+ *
+ * ```javascript
* {
- * access_token: 'ACCESS_TOKEN', //访问token，有效期见expires_in
- * expires_in: 7200, //access_token的有效期，单位为秒
- * refresh_token: 'REFRESH_TOKEN', //刷新token，有效期30天
- * openid: 'OPENID', //用户openid
- * scope: 'SCOPE', //用户授权作用域
+ * access_token: 'ACCESS_TOKEN',
+ * expires_in: 7200,
+ * refresh_token: 'REFRESH_TOKEN',
+ * openid: 'OPENID',
+ * scope: 'SCOPE',
* }
+ * ```
*
- * 参数 | 描述
+ * 字段 | 描述
* ------------- | -------------
* access_token | 网页授权接口调用凭证,注意：此access_token与基础支持的access_token不同
* expires_in | access_token接口调用凭证超时时间，单位（秒）
- * refresh_token | 用户刷新access_token
+ * refresh_token | 刷新凭证
* openid | 用户唯一标识，请注意，在未关注公众号时，用户访问公众号的网页，也会产生一个用户和公众号唯一的OpenID
* scope | 用户授权的作用域，使用逗号（,）分隔
+ *
*/
function refreshToken(appid, refresh_token) {
@@ -198,9 +218,9 @@ function refreshToken(appid, refresh_token) {
/**
* 拉取用户详细
*
- * 仅限授权作用域为 `snsapi_userinfo` 有效
+ * 仅限授权作用域为 `snsapi_userinfo` 有效。
*
- * @param {string} access_token 用户授权得到访问token
+ * @param {string} access_token 网页授权接口调用凭证
* @param {string} openid 用户openid
* @param {string} lang 返回信息的语言版本
* 【可省略】默认为 简体中文
@@ -209,6 +229,8 @@ function refreshToken(appid, refresh_token) {
* - en 英语
* @returns {Promise} 返回一个Promise
* 请求成功则Promise会返回一个Object如下：
+ *
+ * ```javascript
* {
* openid: 'OPENID',
* nickname: 'NICKNAME',
@@ -216,12 +238,13 @@ function refreshToken(appid, refresh_token) {
* province: 'PROVINCE',
* city: 'CITY',
* country: 'COUNTRY',
- * headimgurl: 'http://wx.qlogo.cn/mmopen/g3MonUZtNHkdmzicIlibx6iaFqAc56vxLSUfpb6n5WKSYVY0ChQKkiaJSgQ1dZuTOgvLLrhJbERQQ4eMsv84eavHiaiceqxibJxCfHe/46',
+ * headimgurl: 'http://wx.qlogo.cn/mmopen/g3MonUZtNHkdmzicIlibx6iaFqAc56vxLSUfpb6n5WKSYVY0ChQKkiaJSgQ1dZuTOgvLLrhJbERQQ4eMsv84eavHiaiceqxibJxCfHe/46',
* privilege: ['PRIVILEGE1', 'PRIVILEGE2'],
* unionid: 'o6_bmasdasdsad6_2sgVt7hMZOPfL',
* }
+ * ```
*
- * 字段 | 说明
+ * 字段 | 描述
* ---------- | ---------
* openid | 用户的唯一标识
* nickname | 用户昵称
@@ -271,10 +294,11 @@ function getUserinfo(access_token, openid, lang) {
* 如果授权作用域为 `snsapi_userinfo`，则拉取用户详细信息前可以先检查授权凭证是否有效。
* 如果授权凭证已失效，可调用刷新凭证。
*
- * @param {string} access_token 访问授权凭证
+ * @param {string} access_token 网页授权接口调用凭证
* @param {string} openid 用户openid
* @returns {Promise} 返回一个Promise
* 请求成功则Promise返回一个boolean值，如果是true则凭证有效
+ *
*/
function checkAccessToken(access_token, openid) {
@@ -303,7 +327,6 @@ function checkAccessToken(access_token, openid) {
})
}
-
module.exports = {
getAuthUrl,
getToken,
diff --git a/package.json b/package.json
index 153e851..17a4baf 100644
--- a/package.json
+++ b/package.json
@@ -1,10 +1,11 @@
{
"name": "wxmp-auth",
- "version": "0.1.0",
+ "version": "0.1.1",
"description": "",
"main": "index.js",
"scripts": {
- "test": "echo \"Error: no test specified\" && exit 1"
+ "test": "echo \"Error: no test specified\" && exit 1",
+ "doc": "jsdoc2md index.js > API.md"
},
"keywords": [
"wechat"
@@ -17,7 +18,8 @@
"uuid": "^3.1.0"
},
"devDependencies": {
- "eslint-config-egg": "^5.1.1"
+ "eslint-config-egg": "^5.1.1",
+ "jsdoc-to-markdown": "^3.0.0"
},
"homepage": "https://github.com/binsee/wxmp-auth#readme",
"repository": {