@nativescript-community/https

Nativescript https 请求插件

目录

* [Installation](#installation)
		* [A drop-in replacement for the [default http module](https://docs.nativescript.cn/cookbook/http).](#a-drop-in-replacement-for-the-default-http-modulehttpsdocsnativescriptorgcookbookhttp)
* [Features](#features)
* [FAQ](#faq)
* [Installation](#installation-1)
* [Examples](#examples)
	* [Hitting an API using `GET` method](#hitting-an-api-using-get-method)
* [Configuration](#configuration)
	* [Installing your SSL certificate](#installing-your-ssl-certificate)
		* [Enabling SSL pinning](#enabling-ssl-pinning)
		* [Disabling SSL pinning](#disabling-ssl-pinning)
	* [useLegacy](#uselegacy)
	* [Cookie](#cookie)
	* [Enabling Cache](#enabling-cache)
	* [Multipart form data](#multipart-form-data)
	* [Options](#options)
* [Webpack / bundling](#webpack--bundling)
* [`iOS` Troubleshooting](#ios-troubleshooting)
* [`Android` troubleshooting](#android-troubleshooting)

• 感谢 * 示例：
  • 演示和开发
    • 仓库设置
    • 构建
    • 演示
  • 贡献
    • 更新仓库
    • 更新 README
    • 更新文档
    • 发布
    • 修改子模块
  • 问题

安装

从您的项目根目录运行以下命令

ns plugin add @nativescript-community/https

轻松集成最可靠的本地网络库，并具备最新的 HTTPS 安全特性。

Android：版本 4.x 使用 okhttp 4.x，将 minSDKVersion 修改为 21！如果需要更低版本，请坚持使用 3.x

插件版本 2.0.0 将 iOS 上的 AFNetworking 提升至 4.0.0，不再依赖于 UIWebView。请确保运行 pod repo update 命令以获取开发机器上最新的 AFNetworking pod。

默认 http 模块的替代品。

特性

• 现代 TLS & SSL 安全特性
• 共享连接池减少请求延迟
• 自动从常见连接问题中恢复
• 所有操作都在本地后台线程上运行
• 透明 GZIP
• HTTP/2 支持
• 多部分
• 缓存
• 基本 Cookie 支持

常见问题解答

SSL 密钥固定是什么，以及所有这些安全术语是什么意思？

如何通过 SSL 密钥固定使您的应用更加安全.

我必须使用 SSL 密钥固定吗？

不。 此插件默认情况下无需任何安全配置即可运行。无论如何，您仍然可以享受上述所有功能。

安装

tns plugin add @nativescript-community/https

示例

使用 GET 方法调用 API

import * as Https from '@nativescript-community/https';
Https.request({
    url: 'https://httpbin.org/get',
    method: 'GET',
    timeout: 30, // seconds (default 10)
})
    .then(function (response) {
        console.log('Https.request response', response);
    })
    .catch(function (error) {
        console.error('Https.request error', error);
    });

配置

安装您的 SSL 证书

在您的项目 app 文件夹中创建一个名为 assets 的文件夹，如下所示 <project>/app/assets。使用 chrome，访问 SSL 证书所在的 URL。查看详细信息，然后将证书图片拖放到 assets 文件夹中。

启用 SSL 密钥固定

import { knownFolders } from 'file-system';
import * as Https from '@nativescript-community/https';
let dir = knownFolders.currentApp().getFolder('assets');
let certificate = dir.getFile('httpbin.org.cer').path;
Https.enableSSLPinning({ host: 'httpbin.org', certificate });

一旦您启用了 SSL 密钥固定，您就无法使用不同的 host 或 certificate 文件重新启用。

禁用 SSL 密钥固定

import * as Https from '@nativescript-community/https';
Https.disableSSLPinning();

调用此方法之后的所有请求将不再使用 SSL 密钥固定，直到再次启用。

useLegacy

有一个名为 useLegacy 的新选项。您可以为每个请求选项进行设置。使用该选项时，请求将表现得更像 {N} http 模块。

• 请求返回的 content 不是一个字符串，而是一个对象。它主要遵循 HTTPContent 格式。您可以通过调用 toJSON 或 toFile 来操作。唯一的区别是，toFile 返回一个 Promise<File>，这意味着它是异步的，并在后台线程中运行！
• 错误也会返回一个 content，允许您读取其内容。

Cookie

默认情况下，基本 Cookie 支持已启用，其工作方式类似于 {N} http 模块。将来将添加更多选项。

启用缓存

import { knownFolders, path } from '@nativescript/core/file-system';
import * as Https from '@nativescript-community/https';
Https.setCache({
    diskLocation: path.join(knownFolders.documents().path, 'httpcache'),
    diskSize: 10 * 1024 * 1024, // 10 MiB
});

/// later on when calling your request you can use the cachePolicy option

多部分表单数据

如果您将 Content-Type 头部设置为 "multipart/form-data"，则请求数据将被评估为多部分表单数据。每个请求数据参数都应采用以下格式：

{
	data: any
    parameterName: string,
    fileName?: string
    contentType?: string
}

如果设置了 fileName 和 contentType，则数据预期为 iOS 上的 NSData 或 Android 上的 native.Array。

选项

export interface HttpsSSLPinningOptions {
    host: string;
    certificate: string;
    allowInvalidCertificates?: boolean;
    validatesDomainName?: boolean;
    commonName?: string;
}
import { HttpRequestOptions } from 'tns-core-modules/http';
export interface HttpsRequestOptions extends HTTPOptions {
    useLegacy?: boolean;
    cachePolicy?: 'noCache' | 'onlyCache' | 'ignoreCache';
    onProgress?: (current: number, total: number) => void;
}

Webpack / 打包

由于您可能与应用程序一起打包证书（例如，我们的演示就是这样做的），请确保它也由 Webpack 打包。您可以通过添加证书（s）使用 CopyWebpackPlugin 来完成此操作。

iOS 故障排除

在开始 beef 之前，请先了解 iOS 的 App Transport Security。

如果您尝试访问未添加到 App Transport Security 白名单的 https 路由，则它将不起作用！您可以通过向项目的 Info.plist 中添加以下内容来绕过此行为：

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

此插件不会自动将 NSAllowsArbitraryLoads 添加到您的项目 Info.plist 中。

Android 故障排除

如果您在主线程上执行太多网络操作的消息崩溃，则将选项 allowLargeResponse 的值设置为 true 传递给 request 函数。

谢谢

示例

• 基本
  • 一个基本示例

演示和开发

仓库设置

存储库使用子模块。如果您没有使用 --recursive 进行克隆，则需要调用

git submodule update --init

用于安装和链接依赖项的包管理器必须是 pnpm 或 yarn。npm 不会工作。

要开发和测试：如果您使用 yarn，则运行 yarn；如果您使用 pnpm，则运行 pnpm i。

交互式菜单

要启动交互式菜单，请运行 npm start（或 yarn start 或 pnpm start）。这将列出所有常用脚本。

构建

npm run build.all

警告：似乎 yarn build.all 不会总是起作用（在 node_modules/.bin 中找不到二进制文件），这就是为什么文档明确使用 npm run 的原因。

演示

npm run demo.[ng|react|svelte|vue].[ios|android]

npm run demo.svelte.ios # Example

演示设置在某种意义上有点特殊，即如果您想修改/添加演示，您不需要直接在 demo-[ng|react|svelte|vue] 中工作。相反，您在 demo-snippets/[ng|react|svelte|vue] 中工作。您可以从每种风味的 install.ts 开始，以了解如何注册新演示。

贡献

更新仓库

您可以非常容易地更新存储库文件。

首先更新子模块

npm run update

然后提交更改，然后更新公共文件

npm run sync

然后您可以运行 yarn|pnpm，如果有更改的文件，请提交它们

更新 README

npm run readme

更新文档

npm run doc

发布

发布完全由 lerna 处理（您可以添加 -- --bump major 来强制进行主要版本发布）只需运行即可

npm run publish

修改子模块

该仓库使用 https:// 对于子模块，这意味着您无法直接将子模块推送到远程。一个简单的解决方案是修改 ~/.gitconfig 并添加

[url "ssh://[email protected]/"]
	pushInsteadOf = https://github.com/

问题

如果您有任何问题/问题/评论，请随时在 NativeScript 社区 Discord 中创建问题或开始对话。