@3fv/serverless-offline 中文文档教程

Question

Serverless Offline

注意 只有在 PR 1130 在基础 repo 中获得批准 之后才会发布

这个 Serverless 插件模拟 AWS λ和本地计算机上的 API 网关 以加快您的开发周期。 为此，它会启动一个 HTTP 服务器，像 APIG 一样处理请求的生命周期并调用您的处理程序。

特点：

• Node.js, Python, Rubyλ runtimes.
• Velocity templates support.
• Lazy loading of your handler files.
• And more: integrations, authorizers, proxies, timeouts, responseParameters, HTTPS, CORS, etc…

这个插件是由它的用户更新的，我只是做维护并确保 PR 与社区相关。 换句话说，如果您发现错误或想要新功能，请成为< href="https://github.com/dherault/serverless-offline/graphs/contributors">贡献者：v：！ 请参阅贡献部分。

Documentation

• Installation
• Usage and command line options
• Usage with invoke
• The process.env.IS_OFFLINE variable
• Docker and Layers
• Token authorizers
• Custom authorizers
• Remote authorizers
• JWT authorizers
• Custom headers
• Environment variables
• AWS API Gateway Features
• Velocity Templates
• CORS
• Catch-all Path Variables
• ANY method
• Lambda and Lambda Proxy Integrations
• HTTP Proxy
• Response parameters
• WebSocket
• Usage with Webpack
• Velocity nuances
• Debug process
• Resource permissions and AWS profile
• Scoped execution
• Simulation quality
• Usage with serverless-dynamodb-local and serverless-webpack plugin
• Credits and inspiration
• License
• Contributing
• Contributors

Installation

首先，将 Serverless Offline 添加到您的项目中：

npm install serverless-offline --save-dev

然后在项目的 serverless.yml 文件中的插件部分添加以下条目：<代码>无服务器离线。 如果没有插件部分，您需要将其添加到文件中。

请注意，serverless-offline 的“插件”部分必须位于 serverless.yml 的根级别。

它应该如下所示：

plugins:
  - serverless-offline

您可以通过运行 serverless 命令检查是否已成功安装插件line:

serverless --verbose

控制台应该显示 Offline 作为您的 Serverless 项目中现在可用的插件之一。

Usage and command line options

在您的项目根目录中运行：

serverless offline 或 sls offline。

列出插件运行的所有选项：

sls offline --help

所有 CLI 选项都是可选

--apiKey                    Defines the API key value to be used for endpoints marked as private Defaults to a random hash.
--corsAllowHeaders          Used as default Access-Control-Allow-Headers header value for responses. Delimit multiple values with commas. Default: 'accept,content-type,x-api-key'
--corsAllowOrigin           Used as default Access-Control-Allow-Origin header value for responses. Delimit multiple values with commas. Default: '*'
--corsDisallowCredentials   When provided, the default Access-Control-Allow-Credentials header value will be passed as 'false'. Default: true
--corsExposedHeaders        Used as additional Access-Control-Exposed-Headers header value for responses. Delimit multiple values with commas. Default: 'WWW-Authenticate,Server-Authorization'
--disableCookieValidation   Used to disable cookie-validation on hapi.js-server
--enforceSecureCookies      Enforce secure cookies
--hideStackTraces           Hide the stack trace on lambda failure. Default: false
--host                  -o  Host name to listen on. Default: localhost
--httpPort                  Http port to listen on. Default: 3000
--httpsProtocol         -H  To enable HTTPS, specify directory (relative to your cwd, typically your project dir) for both cert.pem and key.pem files
--ignoreJWTSignature        When using HttpApi with a JWT authorizer, don't check the signature of the JWT token. This should only be used for local development.
--lambdaPort                Lambda http port to listen on. Default: 3002
--noPrependStageInUrl       Don't prepend http routes with the stage.
--noAuth                    Turns off all authorizers
--noTimeout             -t  Disables the timeout feature.
--prefix                -p  Adds a prefix to every path, to send your requests to http://localhost:3000/[prefix]/[your_path] instead. Default: ''
--printOutput               Turns on logging of your lambda outputs in the terminal.
--resourceRoutes            Turns on loading of your HTTP proxy settings from serverless.yml
--useChildProcesses         Run handlers in a child process
--useWorkerThreads          Uses worker threads for handlers. Requires node.js v11.7.0 or higher
--websocketPort             WebSocket port to listen on. Default: 3001
--webSocketHardTimeout      Set WebSocket hard timeout in seconds to reproduce AWS limits (https://docs.aws.amazon.com/apigateway/latest/developerguide/limits.html#apigateway-execution-service-websocket-limits-table). Default: 7200 (2 hours)
--webSocketIdleTimeout      Set WebSocket idle timeout in seconds to reproduce AWS limits (https://docs.aws.amazon.com/apigateway/latest/developerguide/limits.html#apigateway-execution-service-websocket-limits-table). Default: 600 (10 minutes)
--useDocker                 Run handlers in a docker container.
--layersDir                 The directory layers should be stored in. Default: ${codeDir}/.serverless-offline/layers'
--dockerReadOnly            Marks if the docker code layer should be read only. Default: true
--allowCache                Allows the code of lambda functions to cache if supported.
--overrideLayersDir         Forces docker to use a mapped host directory instead of downloading layers, incredibly useful for debugging
--overrideCodeDir           Forces docker to use a mapped host directory instead of package artifact of named handler, incredibly useful for debugging

的：任何 CLI 选项都可以添加到您的 serverless.yml。 例如：

custom:
  serverless-offline:
    httpsProtocol: "dev-certs"
    httpPort: 4000
    stageVariables:
      foo: "bar"

通过命令行传递的选项会覆盖 YAML 选项。

默认情况下，您可以将请求发送到 http://localhost:3000/。 请注意：

• You'll need to restart the plugin if you modify your serverless.yml or any of the default velocity template files.
• When no Content-Type header is set on a request, API Gateway defaults to application/json, and so does the plugin. But if you send an application/x-www-form-urlencoded or a multipart/form-data body with an application/json (or no) Content-Type, API Gateway won't parse your data (you'll get the ugly raw as input), whereas the plugin will answer 400 (malformed JSON). Please consider explicitly setting your requests' Content-Type and using separate templates.

Usage with invoke

要使用 Lambda.invoke，您需要将 lambda 端点设置为无服务器离线端点：

const { Lambda } = require('aws-sdk')

const lambda = new Lambda({
  apiVersion: '2015-03-31',
  // endpoint needs to be set only if it deviates from the default, e.g. in a dev environment
  // process.env.SOME_VARIABLE could be set in e.g. serverless.yml for provider.environment or function.environment
  endpoint: process.env.SOME_VARIABLE
    ? 'http://localhost:3002'
    : 'https://lambda.us-east-1.amazonaws.com',
})

然后可以在处理程序中调用所有 lambda，

exports.handler = async function() {
  const params = {
    // FunctionName is composed of: service name - stage - function name, e.g.
    FunctionName: 'myServiceName-dev-invokedHandler',
    InvocationType: 'RequestResponse',
    Payload: JSON.stringify({ data: 'foo' }),
  }

  const response = await lambda.invoke(params).promise()
}

您也可以使用 aws cli 调用指定 --endpoint-url

aws lambda invoke /dev/null \
  --endpoint-url http://localhost:3002 \
  --function-name myServiceName-dev-invokedHandler

可用函数名称列表及其对应的 serverless.yml 函数键 在服务器启动后列出。 如果您使用自定义命名，这很重要 serverless-offline 函数的方案将使用您的自定义名称。 左侧是 serverless.yml 中的函数键 （下例中的invokedHandler）右边是函数名 用于外部调用函数如aws-sdk （myServiceName-dev-invokedHandler 在下面的示例中）：

serverless offline
...
offline: Starting Offline: local/us-east-1.
offline: Offline [http for lambda] listening on http://localhost:3002
offline: Function names exposed for local invocation by aws-sdk:
           * invokedHandler: myServiceName-dev-invokedHandler

列出为目标公开的可用手动调用路径 通过 aws-sdk 和 aws-cli，使用 SLS_DEBUG=* 和 serverless offline。 调用服务器启动后，将显示完整的端点列表：

SLS_DEBUG=* serverless offline
...
offline: Starting Offline: local/us-east-1.
...
offline: Offline [http for lambda] listening on http://localhost:3002
offline: Function names exposed for local invocation by aws-sdk:
           * invokedHandler: myServiceName-dev-invokedHandler
[offline] Lambda Invocation Routes (for AWS SDK or AWS CLI):
           * POST http://localhost:3002/2015-03-31/functions/myServiceName-dev-invokedHandler/invocations
[offline] Lambda Async Invocation Routes (for AWS SDK or AWS CLI):
           * POST http://localhost:3002/2014-11-13/functions/myServiceName-dev-invokedHandler/invoke-async/

您可以使用 REST 客户端手动定位这些端点以调试您的 lambda 如果你愿意的话。 如果您是 通过 aws-sdk 调用它。

The process.env.IS_OFFLINE variable

将在您的处理程序中为 "true" 并彻底检查插件。

Docker and Layers

要使用无服务器离线层，您需要将 useDocker 选项设置为 true。 这可以通过使用 --useDocker 命令，或者像这样在您的 serverless.yml 中：

custom:
  serverless-offline:
    useDocker: true

这将允许 docker 容器查找有关层的任何信息，下载并使用它们。 为此，您必须使用：

• AWS as a provider, it won't work with other provider types.
• Layers that are compatible with your runtime.
• ARNs for layers. Local layers aren't supported as yet.
• A local AWS account set-up that can query and download layers.

如果您为 AWS 角色使用最低权限主体，则此策略应该可以帮助您：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "lambda:GetLayerVersion",
            "Resource": "arn:aws:lambda:*:*:layer:*:*"
        }
    ]
}

一旦您运行启动 Docker 容器的函数，它将遍历所有层对于该功能，请按顺序将它们下载到您的层文件夹，并保存层的哈希值，以便将来可以重复使用。 如果它们在未来发生变化，您只需要重新下载您的图层。 如果您希望重新下载图层，只需删除图层文件夹即可。

然后您应该能够像往常一样调用函数，并且它们是针对您的 docker 容器中的层执行的。

Additional Options

有 2 个附加选项可用于 Docker 和 Layer 使用。

• layersDir
• dockerReadOnly

layersDir

默认情况下，图层是按项目下载的，但是，如果您想跨项目共享它们，可以将它们下载到一个公共位置。 例如，layersDir: /tmp/layers 将允许它们在项目之间共享。 确保在使用此设置时，您正在写入层的目录可以由 docker 共享。

dockerReadOnly

对于某些编程语言和框架，希望能够写入文件系统以用于使用本地 SQLite 数据库进行测试或其他仅用于测试的修改。 为此，您可以设置 dockerReadOnly: false，这将允许修改本地文件系统。 这并没有严格模仿 AWS Lambda，因为 Lambda 有一个只读文件系统，所以这应该作为最后的手段使用。

Token authorizers

如 无服务器文档 您可以使用 API 密钥作为简单的身份验证方法。

Serverless-offline 将模拟 APIG 的行为并创建一个打印在屏幕上的随机令牌。 使用此令牌，您可以访问将 x-api-key: generatedToken 添加到请求标头的私有方法。 所有 api 密钥将共享相同的令牌。 要指定自定义令牌，请使用 --apiKey cli 选项。

Custom authorizers

仅支持自定义授权方。 自定义授权程序在执行 Lambda 函数之前执行并返回错误或策略文档。

向自定义授权方传递一个 event 对象，如下所示：

{
  "type": "TOKEN",
  "authorizationToken": "<Incoming bearer token>",
  "methodArn": "arn:aws:execute-api:<Region id>:<Account id>:<API id>/<Stage>/<Method>/<Resource path>"
}

methodArn 不包括帐户 ID 或 API ID。

该插件仅支持从标头中检索令牌。 您可以按如下方式配置标头：

"authorizer": {
  "type": "TOKEN",
  "identitySource": "method.request.header.Authorization", // or method.request.header.SomeOtherHeader
  "authorizerResultTtlInSeconds": "0"
}

Remote authorizers

您可以通过在运行 sls offline start 之前设置环境变量 AUTHORIZER 来模拟来自远程授权者的响应

示例：

Unix：export AUTHORIZER='{"principalId": "123"}'

Windows：SET AUTHORIZER='{"principalId": "123"}'

JWT authorizers

对于 HTTP API，JWT 授权方 serverless.yml 中定义的可用于验证令牌和令牌中的范围。 然而此时， JWT 的签名未通过定义的发行者进行验证。 由于这是一个安全风险，此功能是 仅通过 --ignoreJWTSignature 标志启用。 确保只为本地开发工作设置此标志。

Custom headers

您可以在请求中使用一些自定义标头来更好地控制 requestContext 对象。

Header	Event key
cognito-identity-id	event.requestContext.identity.cognitoIdentityId
cognito-authentication-provider	event.requestContext.identity.cognitoAuthenticationProvider

通过这样做，您现在可以使用自定义标头更改这些值。 这可以帮助您更轻松地进行身份验证或从 cognitoAuthenticationProvider 值中检索 userId。

Environment variables

您可以使用环境变量在事件上下文中自定义身份参数。

Environment Variable	Event key
SLSCOGNITOIDENTITYPOOLID	event.requestContext.identity.cognitoIdentityPoolId
SLSACCOUNTID	event.requestContext.identity.accountId
SLSCOGNITOIDENTITY_ID	event.requestContext.identity.cognitoIdentityId
SLS_CALLER	event.requestContext.identity.caller
SLSAPIKEY	event.requestContext.identity.apiKey
SLSCOGNITOAUTHENTICATION_TYPE	event.requestContext.identity.cognitoAuthenticationType
SLSCOGNITOAUTHENTICATION_PROVIDER	event.requestContext.identity.cognitoAuthenticationProvider

您可以使用 serverless-dotenv-plugin 从 .env 文件加载环境变量.

AWS API Gateway Features

Velocity Templates

无服务器文档 ~ AWS doc

您可以提供响应和请求模板对于每个功能。 这是可选的。 为此，您必须将特定于函数的模板文件放置在与函数文件相同的目录中，并将 .req.vm 扩展名添加到模板文件名中。 例如， 如果您的函数在代码文件中：helloworld.js， 您的响应模板应在文件中：helloworld.res.vm，您的请求模板应在文件 helloworld.req.vm 中。

CORS

Serverless doc

如果端点配置将 CORS 设置为 true，插件将使用关联路由的 CLI CORS 选项。 否则，不会添加任何 CORS 标头。

Catch-all Path Variables

AWS doc

像 这样设置贪心路径/store/{proxy+} 将拦截对 /store/list-products、/store/add-product 等的请求...

ANY method

AWS 文档

开箱即用。

Lambda and Lambda Proxy Integrations

无服务器文档 ~ AWS 文档

开箱即用。 请参阅 manual_test 目录中的示例。

HTTP Proxy

无服务器文档 ~ AWS 文档 - AWS::ApiGateway::Method ~ AWS 文档 - AWS::ApiGateway::Resource

示例启用代理：

custom:
  serverless-offline:
    resourceRoutes: true

或

    YourCloudFormationMethodId:
      Type: AWS::ApiGateway::Method
      Properties:
        ......
        Integration:
          Type: HTTP_PROXY
          Uri: 'https://s3-${self:custom.region}.amazonaws.com/${self:custom.yourBucketName}/{proxy}'
          ......

custom:
  serverless-offline:
    resourceRoutes:
      YourCloudFormationMethodId:
        Uri: 'http://localhost:3001/assets/{proxy}'

Response parameters

AWS 文档

您可以使用 ResponseParameters 设置响应的标头。

可能无法正常工作。 请公关。 （难度：很难？）

示例响应速度模板：

"responseParameters": {
  "method.response.header.X-Powered-By": "Serverless", // a string
  "method.response.header.Warning": "integration.response.body", // the whole response
  "method.response.header.Location": "integration.response.body.some.key" // a pseudo JSON-path
},

WebSocket

为了将消息发送回客户端的用法：

POST http://localhost:3001/@connections/{connectionId}

或者，

const apiGatewayManagementApi = new AWS.ApiGatewayManagementApi({
  apiVersion: '2018-11-29',
  endpoint: 'http://localhost:3001',
});

apiGatewayManagementApi.postToConnection({
  ConnectionId: ...,
  Data: ...,
});

在 lambda 处理函数中接收到事件。

支持 websocketsApiRouteSelectionExpression 的基本形式：< code>$request.body.xyz，默认值为$request.body.action。

当前不支持授权者和 wss://。

Usage with Webpack

使用 serverless-webpack 来编译和捆绑你的 ES-next 代码

Velocity nuances

考虑这个用于 POST 端点的 requestTemplate：

"application/json": {
  "payload": "$input.json('$')",
  "id_json": "$input.json('$.id')",
  "id_path": "$input.path('$').id"
}

现在让我们做带有此正文的请求：{ "id": 1 }

AWS 这样解析事件：

{
  "payload": {
    "id": 1
  },
  "id_json": 1,
  "id_path": "1" // Notice the string
}

而离线解析：

{
  "payload": {
    "id": 1
  },
  "id_json": 1,
  "id_path": 1 // Notice the number
}

使用 $input.path 后访问属性将返回一个AWS 上的字符串（期望像 "1" 或 "true" 这样的字符串）但不在 Offline 上（1 或 true >). 您可能会发现其他差异。

Debug process

Serverless 离线插件会响应整体的框架设置，并在调试模式下向控制台输出额外的信息。 为此，您必须设置 SLS_DEBUG 环境变量。 您可以在命令行中运行以下命令以切换到调试模式执行。

Unix：export SLS_DEBUG=*

Windows：SET SLS_DEBUG=*

如果您已经安装了 node-inspector 模块和 chrome 浏览器，您的项目也可以进行交互式调试。 然后，您可以在项目的根目录中运行以下命令行。

初始安装： npm install -g node-inspector

对于每次调试运行： node-debug sls offline

系统会以等待状态启动。 这样也会自动启动chrome浏览器，等待你设置断点进行检查。 根据需要设置断点，然后单击播放按钮继续调试。

根据断点，您可能需要在单独的浏览器窗口中调用函数的 URL 路径，以便运行无服务器函数并使其可用于调试。

Resource permissions and AWS profile

Lambda 函数在执行期间承担 IAM 角色：框架创建此角色并设置 serverless.yml 的 iamRoleStatements 部分中提供的所有权限。

但是，无服务器离线使用您的本地 AWS 配置文件凭据来运行 lambda 函数，这可能会导致一组不同的权限。 默认情况下，aws-sdk 会为您在配置文件中指定的默认 AWS 配置文件加载凭证。

您可以直接在代码中或通过设置适当的环境变量来更改此配置文件。 在将 serverless 离线调用到不同的配置文件之前设置 AWS_PROFILE 环境变量将有效地更改凭据，例如

AWS_PROFILE=; serverless offline

Scoped execution

下游插件可能会绑定到 before:offline:start:end 挂钩以在服务器关闭时释放资源。

Simulation quality

此插件出于许多实际目的模拟 API 网关，足以用于开发 - 但不是完美的模拟器。 具体来说，Lambda 当前在 Node.js v10.x 和 v12.x 上运行 (AWS Docs)，而 Offline 在您自己的运行时上运行，其中没有强制执行内存限制。

Usage with serverless-dynamodb-local and serverless-webpack plugin

运行 serverless offline start。 与 serverless offline 相比，start 命令将触发一个 init 和一个 end 生命周期钩子，这是需要的serverless-offline 和 serverless-dynamodb-local 关闭资源。

将插件添加到您的 serverless.yml 文件：

plugins:
  - serverless-webpack
  - serverless-dynamodb-local
  - serverless-offline # serverless-offline needs to be last in the list

Credits and inspiration

这个插件最初是 Nopik 的 无服务器服务。

License

麻省理工学院

Contributing

是的，谢谢！ 这个插件是社区驱动的，它的大部分功能来自不同的作者。 请更新文档和测试并将您的名字添加到 package.json 文件中。 我们尽量遵循 Airbnb 的 JavaScript 风格指南。

Contributors

dnalborczyk	dherault	computerpunc	leonardoalifraco	daniel-cottone

mikestaub	Bilal-S	dl748	frsechet	zoellner

johncmckim	ThisIsNoZaku	darthtrevino	miltador	gertjvr

juanjoDiaz	perkyguy	jack-seek	hueniverse	robbtraister

dortega3000	ansraliant	joubertredrat	andreipopovici	Andorbal

AyushG3112	franciscocpg	kajwiklund	ondrowan	sulaysumaria

jormaechea	awwong1	c24w	vmadman	encounter

Bob-Thomas	njriordan	bebbi	trevor-leach	emmoistner

OrKoN	adieuadieu	apalumbo	anishkny	cameroncooper

cmuto09	dschep	DimaDK24	dwbelliston	eabadjiev

Arkfille	garunski	james-relyea	joewestcott	LoganArnett

ablythe	marccampbell	purefan	mzmiric5	paulhbarker

pmuens	pierreis	ramonEmilio	rschick	selcukcihan

patrickheeney	rma4ok	clschnei	djcrabhat	adam-nielsen

adamelliottsweeting	againer	alebianco-doxee	koterpillar	triptec

constb	cspotcode	aliatsis	arnas	akaila

ac360	austin-payne	bencooling	BorjaMacedo	BrandonE

guerrerocarlos	chrismcleod	christophgysin	Clement134	rlgod

dbunker	dobrynin	domaslasauskas	enolan	minibikini

em0ney	erauer	gbroques	guillaume	balassy

idmontie	jacintoArias	jgrigg	jsnajdr	horyd

jaydp17	jeremygiberson	josephwarrick	jlsjonas	joostfarla

kenleytomlin	lalifraco-devspark	DynamicSTOP	medikoo	neverendingqs

msjonker	Takeno	mjmac	ojongerius	thepont

WooDzu	PsychicCat	Raph22	wwsno	gribnoysup

starsprung	shineli-not-used-anymore	stesie	stevemao	ittus

tiagogoncalves89	tuanmh	Gregoirevda	gcphost	YaroslavApatiev

zacacollier	allenhartwig	demetriusnunes	hsz	electrikdevelopment

jgilbert01	polaris340	kobanyan	leruitga-ss	livingmine

lteacher	martinmicunda	nori3tsu	ppasmanik	ryanzyy

m0ppers	footballencarta	bryanvaz