c4restfulclient

C4RESTFulClient 说明

简介

C4RESTFulClient是基于request的封装：

• 支持Http、Http协议；
• 支持Cookie；
• response的stream处理；
• 支持对Content-Type和Content-Disposition进行Parser的定义，并在接收response时自动选定；
• 支持GET、POST、PUT、PATCH、DELETE这些METHOD。

配置

配置分为ClientOption和RequestOption：

ClientOption

export interface ClientOption {
    baseURL ?: string,                      // 基地址
    sslOption ?: {                          // SSL的配置项
        cert : Buffer;                      // 证书
        key  : Buffer;                      // 私钥
        passphrase ?: string;               // 证书的密码
        ca ?: string | Buffer | string[] | Buffer[];    // CA
    },
    rejectUnauthorized ?: boolean;          // 是否对证书进行校验（双向验证时需要）
    preambleCRLF ?: boolean;                // 在multipart/form-data请求的边界之前追加/CRLF
    postambleCRLF ?: boolean;               // 在multipart/form-data请求的边界尾部追加/CRLF
    timeout ?: number;                      // 请求超时时间，单位毫秒
    gzip ?: boolean;                        // 是否使用gzip
    cookiesOption ?: {                      // cookie的配置项
        enabled : boolean;                  // 是否开启
        store ?: any;                       // 存储引擎
    };
    downloadPath ?: string;                 // 下载文件的保存目录
};

RequestOption

export interface RequestOption {
    qs ?: { [key : string] : any };             // 请求的查询字符串
    body ?: any;                                // PATCH、POST和PUT请求的实体，必须是Buffer、string或者ReadSteam，如果json项是true，body不许是可序列化的JSON对象
    json ?: boolean;                            // 设置请求实体是否为JSON，会自动在header中增加application/json的Content-Type
    form ?: { [key : string] : any} | string;   // 当传递一个对象或查询字符串时，将body设置为querystring表示的值，并在header中添加application/x-www-form-urlencoded的content-type
    formData ?: { [key : string] : any};        // 传递给multpart/form-data的请求数据
    multipart ?: RequestPart[] | Multipart;     // 用于发送multipart/related的请求数据
    headers ?: Headers;                         // http的headers
    gzip ?: boolean;                            // 是否使用gzip
    cookiesOption ?: {                          // cookie的配置项
        enabled : boolean;                      // 是否开启
        store ?: any;                           // 存储引擎
    };

    // https双向认证
    rejectUnauthorized ?: boolean;              // 是否对证书进行校验（双向验证时需要）
    key ?: Buffer;                              // 私钥
    cert ?: Buffer;                             // 证书
    passphrase ?: string;                       // 证书的密码
    ca?: string | Buffer | string[] | Buffer[]; // CA

    // downloadFileName
    downloadFileName ?: string;                 // 下载文件的保存文件名
}

类s

• C4RESTFulClient

  • 说明：RESTFul客户端

  • 路径：./src/C4RESTFulClient.ts

  • 成员变量：

    • m_DefaultOption，Client的配置，作为请求的默认配置；
    • m_Logger，日志对象；
    • m_Jar，Cookie；
    • m_ContentTypeParsers，处理特定ContentType的Parser的存储字典，key为Content-Type，value为Parser；
    • m_ContentDispositionParsers，处理特定ContentDisposition的Parser的存储字典，key为ContentDisposition，value为Parser；
    • m_DownloadPath，下载文件保存的目录的路径。

  • 成员方法：

    • init

    /**
    * 初始化
    * @param option ClientOption
    */
    async init(option ?: ClientOption)
    

    • addParser

    /**
    * 增加Parser
    * @param parser C4RESTFulParser
    */
    addParser(parser : C4RESTFulParser)
    

    • removeParser

    /**
    * 移除Parser
    * @param name 要移除的Parser的名字
    */
    removeParser(name : string) 
    

    • request

    /**
    * 请求
    * @param url 请求的URL
    * @param method 请求的METHOD
    * @param option RequestOption
    */
    request(url : string, method : string, option : RequestOption) : Promise<Request.Response>
    

    • get

    /**
    * GET Method
    * @param url 请求的URL 
    * @param option RequestOption
    */
    get(url : string, option : RequestOption)
    

    • post

    /**
    * post Method
    * @param url 请求的URL 
    * @param option RequestOption
    */
    post(url : string, option : RequestOption)
    

    • put

    /**
    * put Method
    * @param url 请求的URL 
    * @param option RequestOption
    */
    put(url : string, option : RequestOption)
    

    • patch

    /**
    * patch Method
    * @param url 请求的URL 
    * @param option RequestOption
    */
    patch(url : string, option : RequestOption)
    

    • delete

    /**
    * delete Method
    * @param url 请求的URL 
    * @param option RequestOption
    */
    delete(url : string, option : RequestOption)
    

• C4RESTFulParser

  • 说明：Parser的接口类

  • 路径：./src/C4RESTFulParser.ts

  • 成员变量：

    • name，Parser的名字；
    • isStream，是否是流式解析器；
    • logger，日志类；
    • contentTypes，对应的Content-Type，可以是数组；
    • contentDispositionTypes，对应的Content-Disposition，可以是数组

  • 成员方法：

    • beforeStream，在请求开始调用，用来开始一些stream处理的准备工作；
    • afterStream，在请求结束时调用，用来处理一些stream的收尾工作；
    • parse，进行数据处理

• C4DefaultJSONParser

  • 说明：JSON解析器

  • 路径：./src/C4DefaultRESTFulParser/C4DefaultJSONParser.ts

  • 成员变量：

    • name，Parser的名字；
    • isStream，是否是流式解析器；
    • logger，日志类；
    • contentTypes，对应的Content-Type，可以是数组；

  • 成员方法：

    • parse，进行数据处理

• C4DefaultTextParser

  • 说明：Text解析器

  • 路径：./src/C4DefaultRESTFulParser/C4DefaultTextParser.ts

  • 成员变量：

    • name，Parser的名字；
    • isStream，是否是流式解析器；
    • logger，日志类；
    • contentTypes，对应的Content-Type，可以是数组；

  • 成员方法：

    • parse，进行数据处理

• C4DefaultXMLParser

  • 说明：XML解析器

  • 路径：./src/C4DefaultRESTFulParser/C4DefaultXMLParser.ts

  • 成员变量：

    • name，Parser的名字；
    • isStream，是否是流式解析器；
    • logger，日志类；
    • contentTypes，对应的Content-Type，可以是数组；

  • 成员方法：

    • parse，进行数据处理

• C4DefaultFileStreamParser

  • 说明：文件下载解析器

  • 路径：./src/C4DefaultRESTFulParser/C4DefaultFileStreamParser.ts

  • 成员变量：

    • name，Parser的名字；
    • isStream，是否是流式解析器；
    • logger，日志类；
    • downloadPath，下载文件的保存路径；
    • contentDispositionTypes，对应的Content-Disposition，可以是数组

  • 成员方法：

    • beforeStream，在请求开始调用，用来开始一些stream处理的准备工作；
    • afterStream，在请求结束时调用，用来处理一些stream的收尾工作；
    • parse，进行数据处理

• C4CSVFileStreamParser

  • 说明：CSV文件下载解析器

  • 路径：./src/C4DefaultRESTFulParser/C4CSVFileStreamParser.ts

  • 成员变量：

    • name，Parser的名字；
    • isStream，是否是流式解析器；
    • logger，日志类；
    • downloadPath，下载文件的保存路径；
    • contentTypes，对应的Content-Type，可以是数组；

  • 成员方法：

    • beforeStream，在请求开始调用，用来开始一些stream处理的准备工作；
    • afterStream，在请求结束时调用，用来处理一些stream的收尾工作；
    • parse，进行数据处理