HTTP

导入

通过如下方式导入http api

import http from "svr-api/http";

方法

/**
 * http协议相关API
 */

/**
 * 发起一次http请求。
 * 
 * 现在httpClient可以进行一些个性化的设置，在系统设置中进行配置
 * 
 * 1.HTTPClient连接池大小。系统通过http协议高并发访问第三方服务时需要连接池来提升性能。
 * 	"thresholds.httpClient.maxPoolSize"?: number;
 * 
 * 2.HTTPClient连接空闲时间。http连接池中连接多久不使用时会自动回收，单位毫秒。
 * 	"thresholds.httpClient.maxIDLETime"?: number;
 * 
 * 3.与服务端建立连接的超时时间，超过该时间停止请求
 * 	"thresholds.httpClient.connectionTimeout"?: number;
 * 
 * 4.多长时间检查一次连接是否可用
 * 	"thresholds.httpClient.periodValidateAfterInactivity"?:number;
 * 
 * 5.与服务端建立连接时，等待服务端响应数据的超时时间，超过该时间停止请求
 * 	"thresholds.httpClient.socketTimeout"?: number;
 * 
 * 6.与服务器连接失败时最大重试次数
 * 	"thresholds.httpClient.retryNum"?: number;
 * 
 * 7.发起服务的主机连接到每个路由的最大连接数，最大并发
 * 	"thresholds.httpClient.defaultMaxPerRoute"?: number;
 * 
 * 
 * @param args 请求的参数。
 */
export function request(args: {
	/**请求的url，必须设置 */
	url: string;

	/**可选，默认为`GET`请求，还可以传递`POST` 、 `PUT` 、`DELETE` */
	method?: string;

	/**
	 * 请求参数，如果`method=GET`，那么自动追加到url后面
	 * 若为post请求，且请求参数的内容格式为xml，可直接把xml赋给data,且指定`Content-Type`头信息为application/xml
	 */
	data?: {
		[pname: string]: any;
	} | string;

	/** 
	 * 请求头信息。一般不用指定。
	 * 说明1：POST请求时，如果接收方想获取到json格式的请求参数，那么可以指定`Content-Type`头信息为`application/json`
	 */
	headers?: {
		[p: string]: any;
	}
}): HttpResponseResult;

/**
 * 发起一次http请求。
 * @param url get请求的参数用户自行封装在url中。
 */
export function get(url: string): string;

/**
 * 发起一次post请求。内部会调用request方法
 * @param args 请求的参数
 */
export function post(args: {
	/**请求的url，必须设置 */
	url: string,
	/**请求参数 */
	data?: { [pname: string]: any; } | string,
	/** 
	 * 请求头信息。一般不用指定。
	 * 说明：headers中的Content-Type默认为application/x-www-form-urlencoded
	 */
	headers?: {
		[p: string]: any;
	}
}): HttpResponseResult;

/**
 * 创建一个可以进行会话的http连接，用于连续的对同一个服务器发起多个请求。
 * 
 * @param host 服务器地址，如`http://192.168.7.128:8080`
 */
export function openHttpConnection(host: string): HttpConnection;

/**
 * 创建一个cookie对象，用于设置cookie到浏览器中
 * @param name cookie名
 * @param val  cookie 存储数据的值
 */
export function createCookie(name: string, val: string): Cookie;

/**
 * 返回当前线程所在web线程中的http会话对象。
 * 
 * @returns 返回当前线程所在web线程中的http会话对象。如果当前线程不是web线程，那么返回null。
 */
export function getHttpSession(): HttpSession;

/**
 * 返回当前线程所在web线程中的http请求对象。
 * 
 * @returns 返回当前线程所在web线程中的http请求对象。如果当前线程不是web线程，那么返回null。
 */
export function getHttpServletRequest(): HttpServletRequest;

/**
 * 返回contextpath
 * 
 * @return 返回的字符串符合servlet的contextPath规范，如果没有context返回""，如果有，返回/开头（没有/结尾）的字符串，如/succezbi。
 */
export function getContextPath(): string;

/**
 * 根据传入的文件生成一个下载link，供用户访问下载。下载时是不需要登录，也不需要任何权限的。
 * 
 * @param args 
 * @return 返回一个可以下载文件内容的url，url以/开头，不包含服务器地址、端口号和contextPath，如`/downloadservice/988f3bae-3f35-4d8d-84df-06213e176899`。
 */
export function makeDownloadUrl(args: {
	/**文件对象，或文件路径 */
	file: File | string,
	/**下载时提示的文件名，不传递时自动取文件路径中的名称 */
	fileName?: string,
	/**是否下载完毕一次就删除对象，默认false */
	removeWhenDownloaded?: boolean,
	/**表示此对象的生命周期，以毫秒计算，当超过lifecycle毫秒还没有任何下载请求时，对象将被删除，lifecycle不能小于等于0，不能大于2天。如果lifecycle为0，则相当于将生命周期设置为 */
	lifecycle?: number,
	/**如果内容是gzip格式的，可以设置gzipEncoding为true，使用http的gzip编码协议传输，传输后浏览器自动解压 */
	gzipEncoding?: boolean,
	/**文件类型，如json是`application/json;charset=utf-8`，默认会自动根据文件名后缀猜测， */
	contentType?: string,
}): string;

/**
 * 设置url的参数，如果参数不存在，则添加。
 * @exmaple
 * 	setParameter("http://www.xxxx.com:8080/path/a", "selectId", "123") = "http://www.xxxx.com:8080/path/a?selectId=123"
 * 	setParameter("/path/a", "selectId", "123") = "/path/a?selectId=123"
 * 	setParameter("path/a", "selectId", "123") = "path/a?selectId=123"
 * 	setParameter("http://www.xxxx.com:8080/path/a?id=abc&path=def", "selectId", "123") = "http://www.xxxx.com:8080/path/a?id=abc&path=def&selectId=123"
 * 	setParameter("/path/a?id=abc&path=def", "selectId", "123") = "/path/a?id=abc&path=def&selectId=123"
 * @param url url地址
 * @param parameterName 参数名称
 * @param parameterValue 参数值，里面的特殊字符不用转义，本方法会对参数做转义
 * @return 返回设置参数后的url
 */
export function setParameter(url: string, parameterName: string, parameterValue: string): string;


/**
 * 将url中指定的参数删除，如果该参数不存在，则什么也不做
 * @example
 *  removeParameter("http://www.xxxx.com:8080/path/a?param1=123","param1") = "http://www.xxxx.com:8080/path/a"
 *  removeParameter("http://www.xxxx.com:8080/path/a?param1=123&param2=345","param2") = "http://www.xxxx.com:8080/path/a?param1=123"
 *  removeParameter("/path/a?param1=123","param1") = "/path/a"
 * @param url url地址
 * @param parameterName 要删除的参数名称
 * @return 返回删除参数后的url
 */
export function removeParameter(url: string, parameterName: string): string;

/**
 * 获取系统的httpClientManager
 */
export function getPoolingHttpClientConnectionManager():any;

对象

/**
 * 此文件定义一些http客户端的相关的数据类型。
 * 
 */

/**
 * http请求所返回的结果
 */
declare interface HttpResponseResult {
	/**
	 * 响应状态码，如200,404
	 */
	httpCode: number;
	/**
	 * 响应头数组
	 */
	headers: {
		[header: string]: string;
	}
	/**
	 * 响应体
	 */
	responseText: string;
}

/**
 * 一个Http链接对象，创建一次可多次复用，用于连续多次的向同一个服务器发送请求。
 */
declare interface HttpConnection {

    /**发起一个`GET`请求，url中只需要传递相对地址，如: `/DJXX/main.do` */
	get(url: string): HttpResponseResult;

    /**发起一个http请求，可以指定`GET`、`POST 、`PUT`、`DELETE` */
    request(args: {
       /**请求的url，必须设置 */
		url: string;

		/**可选，默认为`GET`请求，还可以传递`POST` 、 `PUT` 、`DELETE` */
		method?: string;

		/**
		 * 请求参数，如果`method=GET`，那么自动追加到url后面
		 */
		data?: {
			[pname: string]: any;
		}

		/** 
		 * 请求头信息。一般不用指定。
		 * 说明1：POST请求时，如果接收方想获取到json格式的请求参数，那么可以指定`Content-Type`头信息为`application/json`
		 */
		headers?: {
			[p: string]: any;
		}
    }): HttpResponseResult;

    /**
	 * 关闭连接，释放资源
	 * 目前connection是从connectionManager中获取的，不能关闭
	 * @deprecated 
	 */
    close(): void;

	/**
	 * 获取httpClientBuilder对象，通过这个对象可以设置connectionTimeout等参数
	 */
	getHttpClientBuilder(): any;

	/**
	 * 设置最大保持连接时间
	 * @param time 
	 */
	setKeepAliveStrategyTime(time: number): void;
}