stdlib.h_stdlib：在Flash中创建可扩展的Node.js微服务

stdlib.h

Hey everyone - today I have the honor of walking you through using the brand new service registry for microservices, stdlib. You can also check out stdlib on GitHub, which is the open source project we'll be using to generate service scaffolding and take care of package management.

大家好-今天，我很荣幸向您介绍如何使用全新的微服务服务注册表stdlib 。 您还可以在GitHub上检出stdlib ，这是我们将用于生成服务框架并负责软件包管理的开源项目。

什么是stdlib？ (What is stdlib?)

Easy! It's a new take on software registries and package management that you're probably familiar with, like NPM. Instead of focusing on local installations of software, stdlib allows you to write simple microservices with multiple functional HTTP endpoints that you access over-the-wire as remote procedure calls. You can then register these services on the stdlib central registry, at which point they'll be discoverable by others (if you choose to publish them) and also be completely functional web backends. It's actually completely cross-compatible with NPM, if you decide you want to publish your service for local installation as well.

简单！ 这是您可能熟悉的软件注册表和软件包管理的新方法，例如NPM。 stdlib不再关注本地软件安装，而是允许您编写具有多个功能性HTTP终结点的简单微服务，这些终结点可作为远程过程调用通过有线方式访问。 然后，您可以在stdlib中央注册表上注册这些服务，这时其他人(如果您选择发布它们)将可以发现它们，并且它们也将是功能齐全的Web后端。 如果您决定也要发布用于本地安装的服务，则它实际上与NPM完全兼容。

The stdlib registry itself is free to use, for anybody. Instead of others downloading your code, your service itself remains closed-source, with only HTTP endpoints exposed. The actual contents downloadable only by you and your team. Your services can also be run for free, as of writing this article, for up to 500,000 seconds of computation time.

任何人都可以免费使用stdlib 注册表本身。 您的服务本身仍然是开源的 ，而不是其他人下载您的代码，仅公开HTTP端点。 实际内容只能由您和您的团队下载。 在撰写本文时，您的服务还可以免费运行长达500,000秒的计算时间。

You can think about using stdlib a little bit like a mix between NPM and Heroku for microservices, focused on smaller, functional application parts. The potential is vast, you can build a service with any amount of complexity you'd like and never worry about scale or managing infrastructure.

您可以考虑将stdlib有点像NPM和Heroku之间的微服务混合使用，重点是较小的功能应用程序部分。 潜力是巨大的，您可以构建任何所需的复杂性的服务，而不必担心规模或管理基础架构。

入门 (Getting Started)

To get started with stdlib, you'll first have to download the command line tools, available on NPM. You should first have Node 6.X installed, available here, at nodejs.org.

要开始使用stdlib，您首先必须下载NPM上的命令行工具。 您应该首先在nodejs.org上安装Node 6.X( 可从此处获得) 。

Once you've installed node (or if it's installed already), simply run:

一旦安装了节点(或已经安装)，只需运行：

$ npm install -g stdlib.com@1.0.0-dev5

This installs the Developer Preview for CLI tools. There may be newer versions available, so always check out stdlib on GitHub when building new microservices. :)

这将安装用于CLI工具的Developer Preview。 可能会有更新的版本，因此在构建新的微服务时，请始终在GitHub上检查stdlib 。 :)

初始化工作区 (Initializing a Workspace)

To create a stdlib workspace that contains all of your in-development functions, first create a directory you'll be developing in and then initialize stdlib.

要创建一个包含所有开发中函数的stdlib工作区，请首先创建将在其中进行开发的目录，然后初始化stdlib。

$ mkdir stdlib
$ cd stdlib
$ stdlib init

When initializing a workspace, you'll be asked to enter the e-mail address you used to sign up for the registry. You can skip this step with --no-login, but it's not recommended - you won't be able to push code without it! If you don't have an account yet, you'll be able to create one.

初始化工作区时，将要求您输入用于注册注册表的电子邮件地址。 您可以使用--no-login跳过此步骤，但不建议这样做-如果没有它，您将无法推送代码！ 如果您还没有帐户，则可以创建一个帐户。

创建服务 (Creating a Service)

Creating a service is really simple. No need to create a new directory. You should do this from the top-level workspace directory.

创建服务非常简单。 无需创建新目录。 您应该从顶级工作区目录执行此操作。

$ stdlib create

You'll be asked to add a service name, and a default function name. The default function will be the "root" web mapping of your service, if no additional function information is given - though services can support more than one function.

系统将要求您添加服务名称和默认函数名称。 如果未提供其他功能信息，则默认功能将是服务的“根”网络映射-尽管服务可以支持多个功能。

服务剖析 (Anatomy of a Service)

Services have four main components;

服务具有四个主要部分；

package.json (package.json)

package.json is your main service package. This is an NPM-compatible file that contains a "stdlib" field with the following properties:

package.json是您的主要服务包。 这是NPM兼容文件，其中包含具有以下属性的"stdlib"字段：

• "name": The name your service will be published to. Usually in the format <username>/<service>. In order to push your service to the stdlib registry, you'll need to have access to the specified <username>.

  "name" ：您的服务将发布到的名称。 通常采用<username>/<service>格式。 为了将服务推送到stdlib注册表，您需要有权访问指定的<username> 。

• "defaultFunction": The default entry point to your service if no function is provided. Services are accessed by <username>/<service>/<function>, so specifying this field as "main" would make <username>/<service> map to <username>/<service>/main.

  "defaultFunction" ：如果没有提供功能，则为服务的默认入口点。 服务是通过<username>/<service>/<function> ，因此将此字段指定为"main"会使<username>/<service>映射到<username>/<service>/main 。

• "timeout": The timeout, in milliseconds, for service execution. This is the upperbound of compute time applied to all functions in the service.

  "timeout" ：服务执行的超时时间(以毫秒为单位)。 这是应用于服务中所有功能的计算时间的上限。

• "publish": Whether or not to publish publicly to the central registry when your service is pushed to the cloud. A list of public services can be found at the stdlib search page.

  "publish" ：当您的服务推送到云时是否公开发布到中央注册表。 可以在stdlib搜索页面上找到公共服务列表。

env.json (env.json)

A JSON file containing environment variables to be sent to the process.env variable. While working locally, services will load anything in "dev", and when you push a release to stdlib, services will use the values contained in "release". Any other environment names exist for staging purposes in the cloud.

包含要发送到process.env变量的环境变量的JSON文件。 在本地工作时，服务将加载"dev" ，并且当您将发行版推送到stdlib时，服务将使用"release"包含的值。 云中还存在用于暂存目的的任何其他环境名称。

function.json (function.json)

You'll notice a folder, f/, in your main service directory. If you specified your default function name as main, you should see:

您会在主服务目录中注意到一个文件夹f/ 。 如果您将默认函数名称指定为main ，则应该看到：

f/main/function.json
f/main/index.js

In your f/ directory. This is your first functional endpoint!

在您的f/目录中。 这是您的第一个功能端点！

function.json is a JSON file with a few fields;

function.json是具有几个字段的JSON文件；

• "name": The function name. Must match f/<function_path> exactly, or the registry will throw an error.

  "name" ：函数名称。 必须完全匹配f/<function_path> ，否则注册表将引发错误。

• "description": A short description of the function.

  "description" ：功能的简短描述。

• "args": An array containing information about the arguments the function expects. More on this in a bit.

  "args" ：一个数组，其中包含有关函数期望的参数的信息。 对此有更多的了解。

• "kwargs": An object (key-value pairs) containing information about the keywords arguments the function expects. More on this in a bit, too.

  "kwargs" ：一个对象(键值对)，包含有关函数期望的关键字参数的信息。 还有一点更多的信息。

index.js (index.js)

This is paired with a function.json file in a function directory. It's a simple function of the format;

这与功能目录中的function.json文件配对。 这是格式的简单功能；

module.exports = (params, callback) => {
  callback(null, 'hello world');
};

Where params is an object containing the arguments (params.args) and keyword arguments (params.kwargs) passed to the function.

其中params是一个对象，其中包含传递给函数的参数( params.args )和关键字参数( params.kwargs )。

callback is a function callback that ends function execution, expecting an error argument (or null if no error) and a JSON-serializable result (or a Buffer for file processing).

callback是一个结束函数执行的函数回调，期望一个错误参数(如果没有错误，则返回null )和一个JSON可序列化的结果(或一个用于文件处理的Buffer )。

在本地使用服务 (Using Your Service Locally)

The first service you created from stdlib create should have one function that returns "hello world". To run this function (and test it), first go to your service directory:

从stdlib create的第一个服务应该具有一个返回"hello world"函数。 要运行此功能(并对其进行测试)，请首先转到您的服务目录：

$ cd <username>/<service>

If your username is best_developer and you created a service named test, you would do:

如果您的用户名是best_developer并且创建了一个名为test的服务，则可以执行以下操作：

$ cd best_developer/test

Now simply type:

现在只需键入：

$ f .
> "hello world"

Amazing! :) stdlib comes packaged with a command-line testing tool called f, that relies upon the f package from NPM / GitHub to do microservice testing. If you begin your function path with a ., it will search for a local function, otherwise it will run a live function, in the cloud.

惊人！ :) stdlib附带了一个名为f的命令行测试工具，该工具依靠NPM / GitHub的f软件包进行微服务测试。 如果以开头的函数路径. ，它将搜索本地函数，否则它将在云中运行实时函数。

Note that this execution is equivalent to;

注意，此执行等效于;

$ f ./main
> "hello world"

If your "defaultFunction" is set to "main".

如果您的"defaultFunction"设置为"main" 。

在云中注册服务 (Registering Your Service in the Cloud)

There are two ways to register your service. Either in a staging environment, or as a release. Staging environments are mutable and can be overwritten at will. Releases are immutable and can not be overwritten, but they can be torn down.

有两种注册服务的方法。 在登台环境中或作为发行版。 临时环境是可变的 ，可以随意覆盖。 版本是不可变的 ，不能被覆盖，但是它们可以被删除。

注册为登台服务 (Register as a Staging Service)

To push your service to the cloud in a staging environment, use:

要将服务在登台环境中推送到云，请使用：

$ stdlib up <environment>

Where <environment> is the name of your intended staging environment. This name maps directly to the process.env variables stored in env.json, so make sure you use the right name. Your local service runs in dev environment, so that's a good target to test in the cloud as well:

其中<environment>是您预期的暂存环境的名称。 此名称直接映射到env.json存储的process.env变量，因此请确保使用正确的名称。 您的本地服务在dev环境中运行，因此这也是在云中进行测试的好目标：

$ stdlib up dev

This will now register and compile your service. Once complete, you'll be able to run your service in the cloud using;

现在，这将注册并编译您的服务。 完成后，您将可以使用在云中运行服务；

$ f <username>/<service>@dev
> "hello world"

Or, using the example above:

或者，使用上面的示例：

$ f best_developer/test@dev
> "hello world"

You can also access your service over HTTPS via curl or in your browser;

您还可以通过curl或浏览器通过HTTPS访问服务；

https://f.stdlib.com/best_developer/test@dev

Voila! :)

瞧！ :)

注册为发布 (Register as a Release)

Releases are immutable, so make sure you're confident in what you're pushing because though they can be torn down, versions can never be overwritten (or go "back" by semver standards). To release a service, use;

发布是不可变的 ，因此请确保您对要发布的内容充满信心，因为尽管它们可以被删除，但是版本永远不会被覆盖(或按标准标准“退回”)。 要发布服务，请使用；

$ stdlib release

This will register your service with the version specified in package.json. If you would like your service publicly searchable on the registry, set "publish": true in the "stdlib" field of package.json.

这将使用package.json指定的版本注册您的服务。 如果您希望在注册表上公开搜索您的服务 ，请在package.json的"stdlib"字段中设置"publish": true 。

You can view a list of published releases here.

您可以在此处查看已发布版本的列表 。

删除服务 (Removing a Service)

To remove a service, simply type;

要删除服务，只需键入；

$ stdlib down <environment>

or

要么

$ stdlib down -r <version>

Note that stdlib rollback can also be used as a shortcut to remove the currently specified release if published by accident.

请注意，如果意外发布， stdlib rollback还可以用作删除当前指定发行版的快捷方式。

重新启动或重建服务 (Restarting or Rebuilding a Service)

If your service, once published to the cloud, for any reason stops working you can try restarting it with;

如果您的服务一旦发布到云中，由于任何原因停止工作，您可以尝试使用重新启动它；

$ stdlib restart <environment> [-r <version>]

This shouldn't be necessary, but the option exists should you encounter any errors.

这不是必需的，但是如果您遇到任何错误，则该选项存在。

Additionally, you can also rebuild a service. This reinstalls package dependencies and uses the most up-to-date version of the stdlib microservice software. This may be encouraged as we roll out updates, for performance and security reasons.

此外，您还可以重建服务。 这将重新安装软件包依赖性，并使用stdlib微服务软件的最新版本。 出于性能和安全原因，在我们推出更新时可能会鼓励这样做。

$ stdlib rebuild <environment> [-r <version>]

创建更多服务功能 (Creating More Service Functions)

To create additional endpoints to your service (more functions!), simply type:

要为您的服务创建其他端点(更多功能！)，只需键入：

$ stdlib f:create <function>

This will create a new "hello world" function given the newly specified name. Modify it to your heart's content! It is not a default function, so it will need to be accessed using (provided the name new-func);

给定新指定的名称，这将创建一个新的“ hello world”功能。 将其修改为您内心的满意！ 它不是默认功能，因此需要使用(提供了名称new-func )进行访问。

$ f ./new-func

参数和关键字参数 (Arguments and Keyword Arguments)

To pass different params.args and params.kwargs values to your function, use:

要将不同的params.args和params.kwargs值传递给函数，请使用：

$ f . arg0 arg1 --kwarg0 value --kwarg2 "another value"

When accessing services via HTTP GET, all query parameters are converted to keyword arguments.

通过HTTP GET访问服务时，所有查询参数都将转换为关键字参数。

https://f.stdlib.com/user_name/service@version?name=Ed%20Harris

Would set params.kwargs.name equal to the string "Ed Harris".

将params.kwargs.name设置params.kwargs.name等于字符串"Ed Harris" 。

You can also pass any number of arguments or keyword arguments from another application using the f package, as described below.

您还可以使用f软件包从另一个应用程序传递任意数量的参数或关键字参数，如下所述。

从其他应用程序访问您的服务 (Accessing Your Service From Other Applications)

Any service that you put on the stdlib registry can be accessed via other applications using the HTTP endpoints for service, at:

您可以使用HTTP端点服务通过其他应用程序访问您放置在stdlib注册表上的任何服务，网址为：

https://f.stdlib.com/user_name/service@version/function

Node.js (Node.js)

To make this easier, using Node.js you can install the f library, available on GitHub. In the project you wish to access your service from, use:

为了简化此过程，可以使用Node.js安装f库，该库在GitHub上可用 。 在您希望从中访问服务的项目中，使用：

$ npm install f --save

and then in your code...

然后在您的代码中...

const f = require('f');

f('user_name/service@version/function')(arg1, arg2, {kwarg1: 'value'}, (err, result) => {

  if (err) {
    // service errored
  }

  // do something with `result` here!

});

网页浏览器 (Web Browser)

The f library can be used identically in the browser. It's part of the same GitHub repository and can be installed via Bower using poly/f.

f库可以在浏览器中相同地使用。 它是同一GitHub存储库的一部分，可以使用poly/f通过Bower安装。

而已！ (That's it!)

That's all you need to get started with stdlib. I definitely hope you enjoy using it as much as I've enjoyed building it. Stay tuned for more articles showing some sample functions and neat things you can do with microservices.

这就是您开始使用stdlib所需的全部。 我绝对希望您喜欢使用它，就像享受构建它一样。 请继续关注更多文章，这些文章显示了一些示例功能以及微服务可以完成的整洁工作。

Good luck, have fun, and happy building!

祝你好运，玩得开心，建设愉快！

常问问题 (FAQ)

You made it this far, eh? Very thankful for David Walsh for hosting this and being as excited as I am for the future of the project. :)

到目前为止，您做到了吗？ 非常感谢David Walsh主持此活动，并对我对项目的未来感到兴奋。 :)

为什么命名为stdlib？ (Why the name stdlib?)

It's a play on the C Standard Library, or #include <stdlib.h>. We were wondering what you'd call a registry for remote procedure calls on the web and stdlib.com just made the most sense!

这是C标准库或#include <stdlib.h> 。 我们想知道您对Web和stdlib.com上的远程过程调用的注册表叫什么才最有意义！

为什么要使用args(参数)和kwargs(关键字参数)？ (Why args (arguments) and kwargs (keyword arguments)?)

It's a specification from Python, but it works, makes sense, and maps to a ton of other languages we'll be building SDKs for. This way developers can write functions that only expect unnamed arguments, or can specify the names of the arguments they'd like to have passed in.

这是来自Python的规范，但是它可以正常工作，有意义并且可以映射到我们将为其构建SDK的许多其他语言。 这样，开发人员可以编写仅需要未命名参数的函数，或者可以指定他们想要传递的参数的名称。

为什么要使用stdlib？ 为什么不说AWS Lambda？ (Why use stdlib? Why not, say, AWS Lambda?)

stdlib service hosting is actually built on top of AWS Lambda. If that's what you prefer, by all means, we don't want to impede you. stdlib isn't a replacement for Lambda, it's a registry! It's a different offering altogether that augments the "server-less" model to ease your mind completely and give you workflows that your team can organize around so you don't have to build them yourself. stdlib provides easier version control, package management, team tooling and other nifty features.

stdlib服务托管实际上是建立在AWS Lambda之上的。 如果那是您的首选，那么我们绝对不会阻止您。 stdlib不能替代Lambda，它是一个注册表！ 这是完全不同的产品，它增强了“无服务器”模型，从而使您完全放心，并为您的团队提供了可以组织的工作流，因此您不必自己构建它们。 stdlib提供了更轻松的版本控制，程序包管理，团队工具和其他精美功能。

谁创建了stdlib？ (Who created stdlib?)

stdlib was created in a basement by a dog named Ruby. Some say you can still hear her panting when you register a service. All jokes aside, my name is Keith Horwood and I'm known for doing Node and open source stuff. (Ruby is my dog though, and she's beautiful.) I'm probably best known for authoring the popular open source API framework, Nodal. You can follow me on Twitter, @keithwhor but it would be better if you followed our whole company - @Polybit!

stdlib是由一只名为Ruby的狗在地下室中创建的。 有人说您在注册服务时仍然可以听到她的喘息声。 撇开所有笑话，我叫Keith Horwood，我以从事Node和开源工作而闻名。 (尽管Ruby是我的狗，但她很漂亮。)我可能以编写流行的开源API框架Nodal而闻名。 您可以在Twitter上关注我， @ keithwhor，但如果关注我们整个公司- @Polybit ，那就更好了！

我该怎么做？ (How can I contribute?)

Submit a pull request or open an issue on the stdlib GitHub repository. If you want to help us create the future of "server-less" technology, you can also apply to work with us at Polybit. We're new, we're growing, and if you're enthusiastic with good ideas, we want you to join and tell us how to make everything better :).

提交拉取请求或在stdlib GitHub存储库上打开问题。 如果您想帮助我们创造“无服务器”技术的未来，也可以申请Polybit与我们合作 。 我们是新的，我们正在成长，如果您热衷于好主意，我们希望您能加入并告诉我们如何使一切变得更好:)。

翻译自: https://davidwalsh.name/stdlib

stdlib.h