探索Napa：构建Rack API的高效框架

2024-05-20 02:49:08作者：薛曦旖Francesca

napa-v2-01-cropped-resized

Napa是一个简洁的框架，旨在帮助开发者利用Grape、Roar和ActiveRecord快速构建基于Rack的API服务。它的设计灵感来自于Rails，提供了生成器、中间件以及与Rails应用类似的控制台，让API开发和部署变得更加便捷。

安装

Napa以宝石(gem)的形式发布，可以通过以下命令安装：

gem install napa

或者，如果你使用Bundler，在你的Gemfile中添加：

gem 'napa'

然后运行：

$ bundle install

快速上手

查阅快速入门指南，了解如何创建一个简单的Napa服务。

使用

在终端输入napa，你可以看到所有可用的功能：

Commands:
  napa console [ENVIRONMENT]  # 启动Napa控制台
  napa deploy [TARGET]        # 将服务部署到指定目标（如生产环境、预发布等）
  napa generate [COMMAND]     # 生成新代码
  napa help [COMMAND]         # 查看命令或特定命令的帮助信息
  napa new <NAME> [PATH]      # 创建新的Napa应用
  napa server                 # 启动Napa服务器
  napa version                # 显示Napa版本号

控制台

类似于Rails的控制台，通过运行以下命令加载带有应用程序环境的IRB会话：

napa console

部署

Napa提供了一个CLI来通过设置git标签进行部署。这对于基于chef的部署特别有用，当git SHA发生变化时，触发部署。

napa deploy production

如果你想跳过“确定要部署？”的提示，可以使用--confirm标志自动设置标签：

napa deploy production --confirm

Rake任务

执行rake -T查看所有可用的Rake任务：

rake db:create          # 创建数据库
rake db:drop            # 删除数据库
rake db:migrate         # 迁移数据库
rake db:reset           # 创建测试数据库
rake db:schema:dump     # 从db/migrate目录下生成可移植的数据库模式文件
rake db:schema:load     # 根据db/schema.rb文件加载数据库模式
rake db:seed            # 加载db/seeds.rb中的种子数据
rake git:set_tag[tag]   # 设置标签，触发部署
rake git:verify         # 检查git仓库是否准备好部署
rake routes             # 显示所有Grape路由

中间件

Napa内建了许多Rack中间件，可以增加更多功能到你的项目中。

认证

认证中间件为所有请求添加了简单的基于头部的认证层。只需要在请求头中设置'Passwords' = 'Your Password'即可。密码在.env文件中定义。如果需要多个密码，可以用逗号分隔列表。例如：

ALLOWED_HEADER_PASSWORDS='password1,password2'

如果没有认证需求，只需移除该中间件。

健康检查

健康检查中间件增加了/health端点，返回关于你的应用的信息。这是为了监控工具能够标准化监控多个服务的方式。这个端点将返回类似这样的响应：

{
    "name": "service-name",
    "hostname": "host-name",
    "revision": "当前应用的git SHA",
    "pid": 1234,
    "parent_pid": 1233,
    "napa_revision": "正在运行的Napa版本"
}

日志器

日志器模块用于创建统一的日志格式。日志器可通过Rack中间件启用，只需在config.ru文件中添加以下行：

use Napa::Middleware::Logger

你还可以将日志器启用为ActiveRecord的日志器，通过在初始化器中添加如下代码：

ActiveRecord::Base.logger = Napa::Logger.logger

Napa::Logger.logger返回日志对象的单例实例，所以它可以被传递给其他库或直接调用。例如：

Napa::Logger.logger.debug '一些调试消息'

清理敏感日志数据

有些请求可能包含敏感信息，如密码或信用卡号。为了保护这些信息，应从日志中过滤掉它们。要在初始化器中实现这一点，添加以下代码：

Napa::ParamSanitizer.filter_params = [:password, :password_confirmation, :cvv, :card_number]

请注意数组中的键仅作示例，应替换为您参数中包含敏感数据的键。

未过滤的请求示例（...表示其他信息）：

{ ... "message":{"request":{"method":"POST","path":"/example","query":"name=Test%20User%200039\u0026password=password", ... "params":{"name":"Test User 0039","password":"password"} ...}}}

已过滤的请求示例（...表示其他信息）：

{ ... "message":{"request":{"method":"POST","path":"/example","query":"name=Test%20User%200039\u0026password=[FILTERED]", ... "params":{"name":"Test User 0039","password":"[FILTERED]"} ...}}}

StatsD

有两个中间件可用于启用StatsD报告，分别为RequestStats和DatabaseStats。它们可以在config.ru文件中独立启用：

use Napa::Middleware::RequestStats
use Napa::Middleware::DatabaseStats

RequestStats会记录应用的请求计数和响应时间。

DatabaseStats会记录ActiveRecord的查询时间。

配置

要在应用程序中配置StatsD，您需要提供STATSD_HOST和STATSD_PORT环境变量。如有必要，如果您的StatsD主机需要API密钥（如HostedGraphite），则可以通过STATSD_API_KEY环境变量配置。

日志记录

如果您想在日志中看到StatsD的报告，可以将日志器连接到Napa日志器，以便在日志中查看请求。

Statsd.logger = Napa::Logger.logger

缓存

Napa提供了一个简单的ActiveSupport::Cache包装器，让你能像在Rails中一样轻松访问它。Napa.cache提供了ActiveSupport::Cache::Store中所有的方法。例如：

Napa.cache.read
Napa.cache.write
Napa.cache.fetch
...

默认情况下，它使用:memory_store，但你可以通过设置存储方式来使用其他缓存策略，如Memcache：

Napa.cache = :dalli_store

排序

您可以包含名为Napa::SortableApi的选装模块在任何API中。要在helpers块中包含此模块，请添加include SortableApi。

SortableApi接受params[:sort]参数，格式为field1,field2,-field3，其中field1和field2用于升序排序，field3用于降序排序。例如，-field4,field1相当于ORDER BY field4 DESC, field1。

向sorted_from_params(ar_relation, params[:sort])传入一个ActiveRecord::Relation实例作为ar_relation，并传入一个逗号分隔的字段名字符串作为params[:sort]。