阿里云函数计算 + Aglio 实现 API Blueprint markdown 渲染

本文涉及的产品
函数计算FC,每月15万CU 3个月
简介: 这次想聊聊我在写的站里的一个核心的功能——API 文档的编辑与展示。我最初的想法是,使用 Markdown 来编写文档。但是这样在格式上难免不好统一。跟 @BillSJC 聊的时候,他向我推荐了 Swagger 和 API Blueprint。

本文首发于我的博客 阿里云函数计算 + Aglio 实现 API Blueprint markdown 渲染

这次想聊聊我在写的站里的一个核心的功能——API 文档的编辑与展示。我最初的想法是,使用 Markdown 来编写文档。但是这样在格式上难免不好统一。跟 @BillSJC 聊的时候,他向我推荐了 Swagger 和 API Blueprint。这两个都是 API 文档自动生成工具。对比过后,我决定选择 API Blueprint,因为它是使用类似 markdown 的语法进行文档编写的,相比 Swagger 的使用 YAML,API Blueprint 写的 markdown 可读性更强一些:

# GET /message
+ Response 200 (text/plain)

        Hello World!

地鼠不友好

API Blueprint 的官网上 https://apiblueprint.org/ 推荐了从文档编辑到解析、渲染的诸多工具支持。
我的需求是找到一个 API Blueprint 的渲染工具,将我在 Apicon 编写的 markdown 渲染转换成 HTML 文档。但官网展示的这些工具大多都是 Node.js 编写的,我并没有找到支持 Golang 的工具。但我又不想额外在服务器上再维护一个容器,用于专门运行转换 markdown 的 Node.js 代码。
这时,@BillSJC 向我介绍了 Serverless 的概念,同时推荐了阿里云的函数计算。

Serverless?

从字面上意思来理解 Serverless,即无服务器。
将这个概念放在阿里云的函数计算服务上,即我只需要将我实际的业务代码上传到函数计算服务上,然后通过约定好的触发器去调用这个服务。在这其中,我并不需要去关心服务器相关的硬件配置,环境配置,以及运维等这些事情。我只需要专注于业务代码即可。
这可能和我们平时做的 RESTful API 有些相似,RESTful API 其实也可以看做是通过一个 HTTP 触发器,去调用相关服务。虽然二者的最终结果都是一样的,但 RESTful API 的背后,往往是我们的服务器一直在监听是否有请求,一旦有请求来了,就进行处理;而函数计算这个“事件驱动”更像是一个被动的东西,被触发后执行一段事先设定好的步骤,然后结束。

就像一个函数一样,每次执行都是差不多的步骤和内容,前后之间的两次调用并不会有太大的关联和影响。我们可以来看下大厂都在用它在干什么:

新浪微博 - 调用函数将用户上传的图片进行个性化处理
115 - 触发函数对用户上传的日志进行压缩、转换
芒果 TV - 触发函数记录视频文件的属性信息
石墨文档 - 使用函数来处理多用户文档编辑的冲突

这么一看我是选对了,新浪都用来处理图片了,那我用来处理 markdown 岂不也是合情合理?嘛,开始吧!

Aglio 渲染 markdown

API Blueprint 的渲染器我之所以选择 Aglio https://github.com/danielgtaylor/aglio ,是因为它不仅可以自定义主题,还可以自定义模板。这样我就可以将页面中我不需要的标题、导航栏等内容删除,仅保留内容主体。同时 Aglio 不仅支持 CLI 使用,还可以当做一个包,放在项目中调用。
我们先在本地实现一个 markdown 的渲染,再将它改写成函数计算的模式。

先把 Aglio 给拉下来:

yarn add aglio

然后我们就可以开始编写主要的代码了:

let aglio = require('aglio')
let blueprint = `
# GET /message
+ Response 200 (text/plain)
        Hello World!
`

options = {
    themeTemplate: 'index.jade'
};

aglio.render(blueprint, options, function (err, html, warnings) {
    if (err) return console.log(err);
    if (warnings) console.log(warnings);
    console.log(html);
});

这里我使用的是 Aglio 的默认主题,你可以在 Aglio GitHub Repo 的olio-theme分支下载到主题需要的index.jademixins.jade这两个模板文件。然后就可以开始魔改这两个jade文件了:

doctype

include mixins

html
    head
        meta(charset="utf-8")
        style!= self.css
    body.preload
        div
            .row
                .content
                    block content
                        +Content('primary', false)

我这边将导航栏,标题栏、不用的 JavaScript 都去掉了。然后mixins.jade也是按需修改,相关英文的提示我也进行了汉化。最后的效果是这样的:

下面我们来将其部署到阿里云函数计算上。

部署到阿里云函数计算

因为我们这里的文件很多,故使用阿里云提供的fun工具来进行部署。
Mac 安装fun

brew install fun

安装好后,先输入fun config来跟着命令行提示进行基本的设置:

Aliyun Account ID (阿里云ID)
Aliyun Access Key ID ***************    (AK)
Aliyun Secret Access Key ***************    (SAK)
Default region name cn-hongkong        (地区,我是选择跟自己轻量应用一样的地区,方便直接内网调用)
The timeout in seconds for each SDK client invoking 300        (上传代码超时时间)
The maximum number of retries for each SDK client 3        (上传失败后的尝试次数)
Allow to anonymously report usage statistics to improve the tool over time? No        (是否帮助阿里云改进此工具)

有坑注意
第一项Aliyun Account ID填写的是阿里云的账号 ID,并不是登录时填写的账号。账号 ID 可以在基本资料-安全设置中找到。

之后就可以执行fun init来初始化一个服务了。它会给我们创建template.yml文件,我们进行如下配置:

ROSTemplateFormatVersion: '2015-09-01'
Transform: 'Aliyun::Serverless-2018-04-03'
Resources:
  Aglio-Function:
    Type: 'Aliyun::Serverless::Service'
    Properties:
      Description: 'Markdown render'
    Aglio-Function:
      Type: 'Aliyun::Serverless::Function'
      Properties:
        Handler: index.handler
        Runtime: nodejs8
        CodeUri: './'
      Events:
        http-test:
          Type: HTTP
          Properties:
            AuthType: ANONYMOUS
            Methods: ['POST']

注意这里的Events,即创建了一个 HTTP 触发器,仅允许使用 POST 进行调用,且不做鉴权。

有坑注意
在所有触发器中,HTTP 触发器只能在创建服务时添加,之后无法再添加。因此,在使用fun部署项目时,我们通过template.yml文件创建。

下面编写index.js,将我们的业务代码与阿里云函数计算的入口进行对接:

var getRawBody = require('raw-body');
module.exports.handler = function(req, resp, context) {
    let options = {
        themeTemplate: 'index.jade'
    };

    let aglio = require('aglio')
    getRawBody(req, function(err, body) {
        aglio.render(body.toString(), options, function (err, html, warnings) {
            if (err) return console.log(err);
            if (warnings) console.log(warnings);
            resp.send(html);
        });
    }); 

这里通过引入require('raw-body');来获取请求的 body,通过 Aglio 处理后返回。

之后执行fun deploy部署服务。注意:node_modules文件夹的内容也要一并上传,函数计算不会再次进行拉包。

魔改 Aglio

在阿里云函数计算的控制台中调试我们刚才部署的函数,发现会报 502 错误。
问题出在 Aglio 在渲染 markdown 时,会往node_modules目录下写入一个JavaScript的临时缓存文件。但阿里云的函数计算只开放了/tmp目录下的写入权限,其余都是只读。
那么这里我只能魔改 Aglio 源码了。还好函数计算不会使用包管理拉包,它就只用我们传上去的node_modules
问题出在 Aglio 的文件写入那里,我们只需更改写文件的目录即可:
/node_modules/aglio-theme-olio/lib/main.js文件,第 144 行与第 249 行:

// Line 144
//compiledPath = path.join(ROOT, 'cache', (sha1(key)) + ".css");
compiledPath = path.join('/tmp', (sha1(key)) + ".css");

// Line 249
//compiledPath = path.join(ROOT, 'cache', (sha1(key)) + ".js");
compiledPath = path.join('/tmp', (sha1(key)) + ".js");

然后写入的 JavaScript 的临时文件中,有使用require引入node_modules目录其它的包,这里的相对路径我们改成绝对路径,否则还是会报错 502。
还是在main.js文件下,第 236 行:

// Line 236
//return compiled = "var jade = require('jade/runtime');\n" + (jade.compileFileClient(filename, options)) + "\nmodule.exports = compiledFunc;";
return compiled = "var jade = require('/code/node_modules/jade/runtime');\n" + (jade.compileFileClient(filename, options)) + "\nmodule.exports = compiledFunc;";

之后再部署,就可以看到啦~

总结一下吧~

又学到了新的玩意儿呢。对于一些功能单调、而又十分常用的功能,又不想专门放在服务器上花心思去维护,不妨可以尝试一下阿里云的函数计算。Serverless 这个东西,用得好真的可以解决很多问题。
阿里云的fun工具很好用,让我能快速部署从而能进行调试。这一次下来也踩了很多坑,感觉阿里云的这个仅/tmp目录可写的设定就很蠢。他为何不能改成当前代码执行目录可写呢?然后 Aglio 方面,Aglio 可以说是 API Blueprint 目前可定制度最高的工具了,这点不可否认。像临时缓存文件目录写死在node_modules,这个从开发的角度其实也能理解啦。我一开始也不相信自己能魔改成功的哈哈。

然后关于函数计算的定价方面
这个真的不用太担心,阿里云财大气粗。
函数计算-定价

每月免费次数 100 万次!!
128Mb 每月免费秒数:3200000秒!!换算一下大概是 37 天。也就是说我即使一个月内一秒一次地调用都够。
因此对于个人用户来说,函数计算真的是完全免费了。

这里需要注意一下阿里云内存的计算方式,他并不是按照函数运行时的实际内存占用计算的,而是按照你给函数运行环境设定的执行内存计算。
也就是说我设定 1024 Mb 的最大执行内存,即使实际调用时远远没有用到这么多,阿里云还是按照 1024 Mb 来计费。
推荐是设定实际运行内存占用的两倍大小。像我这个 markdown 渲染,一次实际占用内存 66 Mb 左右,因此我选择的是 128 Mb 的执行内存。

接下来要做的就是关掉函数计算的公网访问,然后让 ECS 从内网调用它。如果可以的话,再把函数计算的日志给打开,后面还要继续探索。(≧∇≦)ノ

相关实践学习
【文生图】一键部署Stable Diffusion基于函数计算
本实验教你如何在函数计算FC上从零开始部署Stable Diffusion来进行AI绘画创作,开启AIGC盲盒。函数计算提供一定的免费额度供用户使用。本实验答疑钉钉群:29290019867
建立 Serverless 思维
本课程包括: Serverless 应用引擎的概念, 为开发者带来的实际价值, 以及让您了解常见的 Serverless 架构模式
目录
相关文章
|
3月前
|
分布式计算 运维 搜索推荐
立马耀:通过阿里云 Serverless Spark 和 Milvus 构建高效向量检索系统,驱动个性化推荐业务
蝉妈妈旗下蝉选通过迁移到阿里云 Serverless Spark 及 Milvus,解决传统架构性能瓶颈与运维复杂性问题。新方案实现离线任务耗时减少40%、失败率降80%,Milvus 向量检索成本降低75%,支持更大规模数据处理,查询响应提速。
197 57
|
2月前
|
人工智能 JavaScript API
开发者必备:阿里云百炼 API 调用图文教程
百炼是阿里云推出的大模型服务平台,集成了很多优质的 AI 模型,包括通义千问、DeepSeek 等。
开发者必备:阿里云百炼 API 调用图文教程
|
1月前
|
运维 Cloud Native 应用服务中间件
阿里云微服务引擎 MSE 及 API 网关 2025 年 5 月产品动态
阿里云微服务引擎 MSE 面向业界主流开源微服务项目, 提供注册配置中心和分布式协调(原生支持 Nacos/ZooKeeper/Eureka )、云原生网关(原生支持Higress/Nginx/Envoy,遵循Ingress标准)、微服务治理(原生支持 Spring Cloud/Dubbo/Sentinel,遵循 OpenSergo 服务治理规范)能力。API 网关 (API Gateway),提供 APl 托管服务,覆盖设计、开发、测试、发布、售卖、运维监测、安全管控、下线等 API 生命周期阶段。帮助您快速构建以 API 为核心的系统架构.满足新技术引入、系统集成、业务中台等诸多场景需要
|
2月前
|
运维 Cloud Native 应用服务中间件
阿里云微服务引擎 MSE 及 API 网关 2025 年 4 月产品动态
阿里云微服务引擎 MSE 面向业界主流开源微服务项目, 提供注册配置中心和分布式协调(原生支持 Nacos/ZooKeeper/Eureka )、云原生网关(原生支持Higress/Nginx/Envoy,遵循Ingress标准)、微服务治理(原生支持 Spring Cloud/Dubbo/Sentinel,遵循 OpenSergo 服务治理规范)能力。API 网关 (API Gateway),提供 APl 托管服务,覆盖设计、开发、测试、发布、售卖、运维监测、安全管控、下线等 API 生命周期阶段。帮助您快速构建以 API 为核心的系统架构.满足新技术引入、系统集成、业务中台等诸多场景需要
阿里云微服务引擎 MSE 及 API 网关 2025 年 4 月产品动态
|
2月前
|
人工智能 运维 安全
阿里云 Serverless 助力海牙湾构建弹性、高效、智能的 AI 数字化平台
海牙湾(G-Town)是一家以“供应链+场景+技术+AI”为核心驱动力的科技公司,致力于为各行业提供数字化转型解决方案。通过采用阿里云Serverless架构,解决了弹性能力不足、资源浪费与运维低效的问题。SAE全托管特性降低了技术复杂度,并计划进一步探索Serverless与AI结合,推动智能数字化发展。海牙湾业务覆盖金融、美妆、能源等领域,与多家知名企业建立战略合作,持续优化用户体验和供应链决策能力,保障信息安全并创造可量化的商业价值。未来,公司将深化云原生技术应用,助力更多行业实现高效数字化转型。
219 19
|
2月前
|
人工智能 弹性计算 运维
阿里云邀请您参加 2025 中国 Serverless 用户调查
阿里云邀请您参加 2025 中国 Serverless 用户调查
|
3月前
|
Cloud Native Serverless 流计算
云原生时代的应用架构演进:从微服务到 Serverless 的阿里云实践
云原生技术正重塑企业数字化转型路径。阿里云作为亚太领先云服务商,提供完整云原生产品矩阵:容器服务ACK优化启动速度与镜像分发效率;MSE微服务引擎保障高可用性;ASM服务网格降低资源消耗;函数计算FC突破冷启动瓶颈;SAE重新定义PaaS边界;PolarDB数据库实现存储计算分离;DataWorks简化数据湖构建;Flink实时计算助力风控系统。这些技术已在多行业落地,推动效率提升与商业模式创新,助力企业在数字化浪潮中占据先机。
222 12
|
3月前
|
运维 Cloud Native 应用服务中间件
阿里云微服务引擎 MSE 及 云原生 API 网关 2025 年 3 月产品动态
阿里云微服务引擎 MSE 面向业界主流开源微服务项目, 提供注册配置中心和分布式协调(原生支持 Nacos/ZooKeeper/Eureka )、云原生网关(原生支持Higress/Nginx/Envoy,遵循Ingress标准)、微服务治理(原生支持 Spring Cloud/Dubbo/Sentinel,遵循 OpenSergo 服务治理规范)能力。API 网关 (API Gateway),提供 APl 托管服务,覆盖设计、开发、测试、发布、售卖、运维监测、安全管控、下线等 API 生命周期阶段。帮助您快速构建以 API 为核心的系统架构.满足新技术引入、系统集成、业务中台等诸多场景需要
|
3月前
|
SQL 分布式计算 Serverless
鹰角网络:EMR Serverless Spark 在《明日方舟》游戏业务的应用
鹰角网络为应对游戏业务高频活动带来的数据潮汐、资源弹性及稳定性需求,采用阿里云 EMR Serverless Spark 替代原有架构。迁移后实现研发效率提升,支持业务快速发展、计算效率提升,增强SLA保障,稳定性提升,降低运维成本,并支撑全球化数据架构部署。
314 56
鹰角网络:EMR Serverless Spark 在《明日方舟》游戏业务的应用
|
3月前
|
人工智能 开发框架 安全
Serverless MCP 运行时业界首发,函数计算让 AI 应用最后一公里提速
作为云上托管 MCP 服务的最佳运行时,函数计算 FC 为阿里云百炼 MCP 提供弹性调用能力,用户只需提交 npx 命令即可“零改造”将开源 MCP Server 部署到云上,函数计算 FC 会准备好计算资源,并以弹性、可靠的方式运行 MCP 服务,按实际调用时长和次数计费,欢迎你在阿里云百炼和函数计算 FC 上体验 MCP 服务。
347 29

热门文章

最新文章