node-easywechat 2.10.2 → 3.0.0-beta.1

package/README.md

@@ -1,11 +1,11 @@
 
 ## EasyWechat for Node.js
 
-[![Build Status](https://app.travis-ci.com/hpyer/node-easywechat.svg?branch=2.x)](https://app.travis-ci.com/hpyer/node-easywechat) [![npm](https://img.shields.io/npm/v/node-easywechat.svg)](https://www.npmjs.com/package/node-easywechat) [![License](https://img.shields.io/npm/l/node-easywechat.svg)](LICENSE)
+[![Build Status](https://app.travis-ci.com/hpyer/node-easywechat.svg?branch=3.x)](https://app.travis-ci.com/hpyer/node-easywechat) [![npm](https://img.shields.io/npm/v/node-easywechat.svg)](https://www.npmjs.com/package/node-easywechat) [![License](https://img.shields.io/npm/l/node-easywechat.svg)](LICENSE)
 
-**注：2.x分支针对 EasyWechat 的 5.x版本(由于4.x与5.x的结构基本一致，就不升级大版本了)。**
+**注：3.x分支针对 EasyWechat 的 6.x版本。**
 
-~~若您需要 EasyWechat 的 3.x版本，请切换到 [1.x](https://github.com/hpyer/node-easywechat/tree/1.x) 分支。~~ **1.0版本已废弃**
+若您需要 EasyWechat 的 5.x版本，请切换到 [2.x](https://github.com/hpyer/node-easywechat/tree/2.x) 分支。
 
 [EasyWechat](https://github.com/w7corp/easywechat) 是一个由 `安正超` 大神用 PHP 开发的开源的微信非官方 SDK（现由微擎团队团队维护）。其功能强大，使用方便，个人一直很喜欢，所以近日将其在 Node.js 上实现。本人会尽量还原其配置项以及接口的调用方式，但毕竟语言环境不同，具体的实现方式会有些许差别，还请各位开发者见谅。
 
@@ -14,78 +14,71 @@
 
 ### 安装
 
-`npm install -S node-easywechat`
+`npm install -S node-easywechat@next`
 
 ### 使用说明
 
 绝大部分API都可以根据 [EasyWechat 的文档](https://www.easywechat.com/5.x/) 来使用。小部分（如获取请求相关数据、返回响应数据、支付证书等）的操作，由于语言环境的不同，会有不同处理。具体可以查看 [node-easywechat-demo](https://github.com/hpyer/node-easywechat-demo/) 以及下方的[自定义模块说明](#自定义模块模块替换使用方法) 。如果仍有疑问，请提issue，谢谢～
 
+从 `3.x` 起 SDK 中不再内置具体业务的接口，仅封装底层基础部分，如认证、授权和 API 客户端。至于为什么不再封装业务接口，可以查看 [EasyWechat 给出说明](https://easywechat.com/6.x/introduction.html#不再封装业务接口)。
+
 ```js
 // 公众号
-let officialAccount = new EasyWechat.Factory.OfficialAccount({
-  // ...
+const { OfficialAccount } = require('node-easywechat');
+// 实例化应用
+let app = new OfficialAccount({
+  // 配置项
 });
 
 // 小程序
-let miniProgram = new EasyWechat.Factory.MiniProgram({
-  // ...
+const { MiniApp } = require('node-easywechat');
+// 实例化应用
+let app = new MiniApp({
+  // 配置项
 });
 
-// 微信支付
-let payment = new EasyWechat.Factory.Payment({
-  // ...
-});
+// ----- 以下为通用的 api 调用方法 -----
 
-// 开放平台
-let openPlatform = new EasyWechat.Factory.OpenPlatform({
-  // ...
-});
+// 获取 api 调用客户端
+let client = app.getClient();
 
-// 企业微信
-let openPlatform = new EasyWechat.Factory.Work({
-  // ...
+// 请求 api
+let response = await client.post('/cgi-bin/user/info/updateremark', {
+  openid: 'xxxx',
+  remark: 'xxxx',
 });
+```
 
-// 小微商户
-let microMerchant = new EasyWechat.Factory.MicroMerchant({
-  // ...
-});
+### 配置项示例
 
-// 企业微信开放平台
-let openWork = new EasyWechat.Factory.OpenWork({
-  // ...
-});
+``` js
+// 通用配置，即所有模块都可以设置
+{
+  // axios 请求参数
+  // 详见：https://github.com/axios/axios#request-config
+  http: {},
 
-// 通用方式
-let app = EasyWechat.Factory.getInstance('OficialAccount', {
-  // ...
-});
+  // 缓存以文件(默认设置)存储时，需要的配置项
+  file_cache: {
+    path: './cache/', // 文件存储目录（请确保该目录有读写权限）
+    fileMode: 0o666,  // 文件权限
+    ext: '.cache'     // 文件扩展名
+  }
+}
 ```
 
-### 配置项示例
-
 ``` js
 // 公众号配置
 {
-  // 微信公众号的 app key
+  // 公众号的 app key
   app_id: '',
-  // 微信公众号的 app secret
+  // 公众号的 app secret
   secret: '',
-  // 微信公众号的 token
+  // 公众号的 token
   token: '',
   // EncodingAESKey
   aes_key: '',
 
-  // 缓存以文件(默认设置)存储时，需要的配置项
-  file_cache: {
-    path: './cache/', // 文件存储目录（请确保该目录有读写权限）
-    fileMode: 0o666,  // 文件权限
-    ext: '.cache'     // 文件扩展名
-  },
-  // 自定义缓存驱动
-  // 您需要实现一个继承 EasyWechat.CacheInterface 的缓存驱动类
-  // 实例化以后利用 “模块替换” 功能赋值给 app.cache
-
   // 网页授权认证
   oauth: {
     // 网页授权类型
@@ -96,251 +89,134 @@ let app = EasyWechat.Factory.getInstance('OficialAccount', {
 }
 ```
 
-``` js
-// 微信支付配置
-{
-  // 应用的 app_id
-  app_id: 'xxx',
-  // 商户号
-  mch_id: 'your-mch-id',
-  // 签名密钥
-  key: 'key-for-signature',
-  // 默认回调地址，也可以在下单时单独设置来覆盖它，完整URL，不带参数
-  notify_url: 'http://xxx.com/pay/notify',
-  // 证书地址，Node.js 只需要 apiclient_cert.p12 证书文件即可
-  cert_path: 'path/to/your/apiclient_cert.p12', // XXX: 绝对路径！！！！
-}
-```
-
 ``` js
 // 小程序配置
 {
-  // appId
-  app_id: 'your-app-id',
-  // appSecret
-  secret: 'your-app-secret'
-}
-```
-
-``` js
-// 企业微信配置
-{
-  // corpId
-  corp_id: 'your-corp-id',
-  // agentId
-  agent_id: 'your-agent-id',
-  // appSecret
-  secret: 'your-app-secret'
-}
-```
-
-``` js
-// 小微商户配置
-{
-  // 商户号
-  mch_id: 'your-mch-id',
-  // 签名密钥
-  key: 'key-for-signature',
-  // V3版本签名密钥
-  apiv3_key: 'apiv3_key-for-signature',
-  // 证书地址，Node.js 只需要 apiclient_cert.p12 证书文件即可
-  cert_path: 'path/to/your/apiclient_cert.p12', // XXX: 绝对路径！！！！
-
-  // 以下两项配置在获取证书接口时可为空，在调用入驻接口前请先调用获取证书接口获取以下两项配置,如果获取过证书可以直接在这里配置，也可参照本文档获取平台证书章节中示例
-  // serial_no: '获取证书接口获取到的平台证书序列号',
-  // certificate: '获取证书接口获取到的证书内容'
-}
-```
-
-``` js
-// 开放平台
-{
-  // 开放平台APPID
-  app_id: 'your-app-id',
-  // 开放平台Secret
-  secret: 'your-secret',
-  // 开放平台Token
-  token: 'your-token',
-  // 开放平台AES KEY
-  aes_key: 'your-aes_key',
-}
-```
-
-``` js
-// 企业微信开放平台
-{
-  // 服务商的corpid
-  corp_id: 'your-corp_id',
-  // 服务商的secret
-  secret: 'your-secret',
-  // 应用id
-  suite_id: 'your-suite_id',
-  // 应用secret
-  suite_secret: 'your-suite_secret',
-  // 应用Token
-  token: 'your-token',
-  // 应用AESKey
-  aes_key: 'your-aes_key',
-  // 注册定制化模板ID
-  reg_template_id: 'your-tpl_id',
-  // 安装应用的回调url（可选）
-  redirect_uri_install: 'your-uri_install',
-  // 单点登录回调url（可选）
-  redirect_uri_single: 'your-uri_single',
-  // 网页授权第三方回调url（可选）
-  redirect_uri_oauth: 'your-uri_oauth',
+  // 小程序的 app key
+  app_id: '',
+  // 小程序的 app secret
+  secret: '',
+  // 小程序的 token
+  token: '',
+  // EncodingAESKey
+  aes_key: ''
 }
 ```
 
-### 模块支持情况
-
-- [x] 公众号模块
-- [x] 微信支付
-- [x] 小程序
-- [x] 开放平台
-- [x] 企业微信
-- [x] 企业微信开放平台
-- [x] 小微商户
-- [x] 自定义
-
 ### 自定义模块（模块替换）使用方法
 
-使用自定义模块的主要目的，是为了消除不同框架、不同软件包的使用方法所带来的差异，以提升 node-easywechat 的使用效率。下面就来说说几个主要模块的自定义方法。
+#### 日志模块
 
-##### 日志模块（log）
-
-> 注：自 `2.6.10` 版本起，配置项中新增了 `debug` 字段，默认为 `false`。设置为 `true` 时，程序才会打印相关日志。所以，如果你只是希望关闭日志的话，更新到 `2.6.10` 即可。
+框架默认不记录任何日志。如果需要，可以通过 `client` 实例的 `setLogger` 方法设置日志处理回调方法。
 
 ```js
-// 创建实例
-const Easywechat = require('node-easywechat');
-let officialAccount = new Easywechat.Factory.OfficialAccount({
-  ...
+// 以公众号为例
+const { OfficialAccount } = require('node-easywechat');
+// 实例化应用
+let app = new OfficialAccount({
+  // ...
 });
 
-// 自定义日志处理方法
-const myLogger = (app) => {
-  // 注意：这里返回的方法不能使用箭头函数，否则会导致获取到的 arguments 异常
-  // 若需要关闭日志，则返回空的函数即可
-  return function() {
-    // 判断是否开启了 debug
-    if (!app['config']['debug']) return true;
-
-    let args = arguments;
-    args[0] = 'myLogger: ' + args[0];
-    return console.log.apply(null, arguments);
-  }
-}
-
-// 使用 rebind 方法，将 myLogger 绑定为 log 模块
-officialAccount.rebind('log', myLogger);
+// 获取 api 调用客户端
+let client = app.getClient();
+
+/**
+ * 该回调方法会接收两种日志信息
+ * 1、接口请求调用前的参数：
+ *  string  固定值，'before'
+ *  object  请求参数
+ * 2、接口请求调用后的参数：
+ *  string  固定值，'after'
+ *  object  请求参数
+ *  number  请求耗时（ms）
+ *  Response  请求响应对象
+ */
+client.setLogger((...args) => {
+  console.log(args)
+});
 ```
 
-##### 请求模块（request）
-
-```js
-// request 模块需实例化 EasyWechat.Http.Request 类
-// 实例化时，需要传入 IncomingMessage 实例
-let request = new EasyWechat.Http.Request(req);
-
-// 当然，由于 IncomingMessage 的 body 流的特殊性，某些框架（目前已知：fastify）
-// 可能会自动读取后挂载到上下文中，从而导致 node-easywechat 去尝试读取时报错。
-// 这时可以选择传入第二个参数，即post的内容
-// 支持 Buffer、object对象、JSON字符串、XML字符串、QueryString格式的POST内容字符串
-let request = new EasyWechat.Http.Request(req, content);
-
-// 若此法方法仍不能满足你的需求，可以选择继承 EasyWechat.Http.Request 类，
-// 并重写其中相关的方法
-// 参考：https://github.com/hpyer/node-easywechat/issues/5
-
-// 使用 rebind 方法，绑定 request 实例
-officialAccount.rebind('request', request);
-```
+#### 缓存模块
 
-##### 缓存模块（cache）
+框架默认使用文件缓存读取到的 `access_token` 等值，如需要改用其他缓存方式（如：redis），请实现接口 `CacheInterface` 并通过 `app.setCacher` 方法进行模块替换。
 
 ```js
-// cache 模块需要您继承并实例化 EasyWechat.CacheInterface 接口
-// 以 redis 为例
-const Redis = require('redis');
-const BlueBird = require('bluebird');
-
-BlueBird.promisifyAll(Redis.RedisClient.prototype);
-BlueBird.promisifyAll(Redis.Multi.prototype);
-
-class RedisCache extends EasyWechat.CacheInterface
-{
-  constructor (options)
-  {
-    super();
+const { OfficialAccount, CacheInterface } = require('node-easywechat');
+const Redis = require("ioredis");
 
-    this.$client = null;
-    try {
-      this.$client = Redis.createClient(options);
-    }
-    catch (e) {
-      console.log('无法创建Redis客户端', e);
-    }
+class RedisCacher extends CacheInterface {
+  constructor(redis) {
+    this.redis = redis;
   }
 
-  async get(id)
+  get(id)
   {
-    if (!this.$client) return false;
-    let content = null;
-    try {
-      content = JSON.parse(await this.$client.getAsync(id));
-    }
-    catch (e) {
-      console.log('获取Redis缓存失败', id, e);
-      return false;
-    }
-    return content;
+    return this.redis.get(id);
   }
 
   async has(id)
   {
-    if (!this.$client) return false;
-    try {
-      let res = await this.$client.existsAsync(id);
-      return res == 1;
-    }
-    catch (e) {
-      return false;
-    }
+    return (await this.redis.exists(id)) > 0;
   }
 
   async set(id, data = null, lifeTime = 0)
   {
-    if (!this.$client) return false;
-    try {
-      if (lifeTime > 0) {
-        await this.$client.setAsync(id, JSON.stringify(data), 'EX', lifeTime);
-      }
-      else {
-        await this.$client.setAsync(id, JSON.stringify(data));
-      }
+    if (lifeTime > 0) {
+      await this.redis.set(id, data, 'EX', lifeTime);
     }
-    catch (e) {
-      console.log('设置Redis缓存失败', id, data, e);
-      return false;
+    else {
+      await this.redis.set(id, data);
     }
     return true;
   }
 
   async delete(id)
   {
-    if (!this.$client) return false;
-    try {
-      let res = await this.$client.delAsync(id);
-      return true;
-    }
-    catch (e) {
-      return false;
-    }
+    await this.redis.del(id);
+    return true;
   }
 }
-let redisCache = new RedisCache(req);
 
-// 使用 rebind 方法，绑定 cache 实例
-officialAccount.rebind('cache', redisCache);
+// 实例化应用
+let app = new OfficialAccount({
+  // ...
+});
+
+// 替换缓存实例
+app.setCacher(new RedisCacher(new Redis));
+```
+
+#### 请求模块
+
+通常，如果你的应用不需要处理服务端回调、支付回调等逻辑的话，是不需要传递请求对象的。
+
+```js
+const { OfficialAccount, ServerRequest } = require('node-easywechat');
+
+// 实例化应用
+let app = new OfficialAccount({
+  // ...
+});
+
+// 根据 IncomingMessage 实例（即 Node.js 原始请求对象）创建 ServerRequest 实例
+//
+// 由于 IncomingMessage 的 body 流的特殊性，某些框架（目前已知：fastify）
+// 可能会自动读取后挂载到上下文中，从而导致 node-easywechat 去尝试读取时报错。
+// 这时可以选择传入第二个参数，即 body 的内容
+//
+// 如果此方法 不能解决你的问题，可以选择继承 ServerRequest，重写相关方法
+let request = ServerRequest.createFromIncomingMessage(req);
+
+// 设置请求实例
+app.setRequest(request);
 ```
+
+### 模块支持情况
+
+- [x] 公众号模块
+- [ ] 微信支付
+- [x] 小程序
+- [ ] 开放平台
+- [ ] 企业微信
+- [ ] 企业微信开放平台
+- [ ] 自定义

package/dist/Core/Cache/FileCache.d.ts

@@ -1,12 +1,13 @@
 import CacheInterface from '../Contracts/CacheInterface';
-import { EasyWechatConfigCacheFile } from '../Types';
-export default class FileCache implements CacheInterface {
+import { CacheFileConfig } from '../../Types/global';
+declare class FileCache implements CacheInterface {
     private options;
-    constructor(options?: EasyWechatConfigCacheFile);
-    getCacheFile(id: string): string;
-    getCacheContent(file: string): string;
+    constructor(options?: CacheFileConfig);
+    protected getCacheFile(id: string): string;
+    protected getCacheContent(file: string): string;
     get(id: string): Promise<any>;
     has(id: string): Promise<boolean>;
     set(id: string, data?: any, lifeTime?: number): Promise<boolean>;
     delete(id: string): Promise<boolean>;
 }
+export = FileCache;

package/dist/Core/Cache/FileCache.js

@@ -11,10 +11,10 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
-Object.defineProperty(exports, "__esModule", { value: true });
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
-const Utils_1 = require("../Utils");
+const merge_1 = __importDefault(require("merge"));
+const Utils_1 = require("../Support/Utils");
 class FileCache {
     constructor(options = null) {
         this.options = {
@@ -24,7 +24,7 @@ class FileCache {
             ext: '.cache'
         };
         if (options && typeof options == 'object') {
-            this.options = (0, Utils_1.merge)({
+            this.options = (0, merge_1.default)({
                 path: './',
                 dirMode: 0o777,
                 fileMode: 0o666,
@@ -45,7 +45,7 @@ class FileCache {
         }
     }
     getCacheFile(id) {
-        return this.options.path + 'node-easywechat.file_cache.' + id + this.options.ext;
+        return this.options.path + id + this.options.ext;
     }
     getCacheContent(file) {
         let dataItem = JSON.parse(fs_1.default.readFileSync(file, {
@@ -116,5 +116,5 @@ class FileCache {
         });
     }
 }
-exports.default = FileCache;
 ;
+module.exports = FileCache;

package/dist/Core/Config.d.ts

@@ -0,0 +1,66 @@
+import { OfficialAccountConfig, MiniAppConfig, PayConfig, OpenPlatformConfig, WorkConfig, OpenWorkConfig } from "../Types/global";
+import ConfigInterface from "./Contracts/ConfigInterface";
+declare class Config implements ConfigInterface {
+    protected items: OfficialAccountConfig | MiniAppConfig | PayConfig | OpenPlatformConfig | WorkConfig | OpenWorkConfig;
+    protected requiredKeys: string[];
+    constructor(items?: OfficialAccountConfig | MiniAppConfig | PayConfig | OpenPlatformConfig | WorkConfig | OpenWorkConfig);
+    /**
+     * 检查是否有配置项缺失
+     * @returns
+     */
+    checkMissingKeys(): boolean;
+    /**
+     * 获取所有配置项
+     * @returns
+     */
+    all(): object;
+    /**
+     * 判断配置项是否存在
+     * @param key
+     * @returns
+     */
+    has(key: string): boolean;
+    /**
+     * 设置配置项
+     * @param key
+     * @param value
+     */
+    set(key: string, value: any): void;
+    /**
+     * 获取配置项
+     * @param key
+     * @param defaultValue
+     * @returns
+     */
+    get(key: string | string[] | Record<string, any>, defaultValue?: any): any;
+    /**
+     * 获取多个配置项
+     * @param keys 键名列表 或者 {键名:默认值} 格式的对象
+     * @returns
+     */
+    getMany(keys: string[] | Record<string, any>): object;
+    /**
+     * 判断配置项是否存在
+     * @param key
+     * @returns
+     */
+    offsetExists(key: any): boolean;
+    /**
+     * 获取配置项
+     * @param key
+     * @returns
+     */
+    offsetGet(key: any): any;
+    /**
+     * 设置配置项
+     * @param key
+     * @param value
+     */
+    offsetSet(key: any, value: any): void;
+    /**
+     * 删除配置项
+     * @param key
+     */
+    offsetUnset(key: any): void;
+}
+export = Config;