搜索

Rust模板引擎askama快速入门

邓胖

共 9050字，需浏览 19分钟

 ·

2024-04-11 13:05

模板引擎很多时候还是很有用的，无论是后端渲染网页还是生成一些文本，其中以Jinja比较出名，而本文的Rust库askama正是Jinja的Rust版实现，如果你对Jinja的语法比较熟悉的话，使用askama应该不会太难上手。

本文Cargo.toml所有代码的依赖

      
      [dependencies]
askama = "0.12.1"
axum = "0.7.4"
tokio = { version = "1.36.0", features = ["full"] }

快速入门

一般来说，模板都是在templates目录下的一个文件，这里为了简单起见这里就不使用文件的形式了。

      
      use askama::Template;


#[derive(Template)]
#[template(source = "Hello {{name}}", ext="txt")]
struct QuickStart {
    name: String
}

fn main() {
    let quickstart = QuickStart{name: String::from("youerning.top")};
    println!("{}", quickstart.render().expect("渲染模板失败:"));
}

askama支持两种模板形式，一种就是上述这种直接通过souce属性设置，另一种就是将模板单独放在templates目录下的文件里面，比如下面这样的目录结构。

      
      .
├── Cargo.lock
├── Cargo.toml
├── src
│   └── main.rs
└── templates
    └── quickstart.txt

所以上面的例子还可以这样写。

      
      use askama::Template;

#[derive(Template)]
#[template(path="quickstart.txt")]
struct QuickStart{
  name: String,
}

fn main() {
  let quick_start = QuickStart{name: String::from("youerning.top")};
  println!("{}", quick_start.render().unwrap());
}

而quickstart.txt的文件内容如下

      
      hello {{name}}

渲染结果都是一样的: hello youerning.top

值得注意的是, 其实我们可以将name字段设置成&'a str的格式, 比如下面这样。

      
      struct QuickStart<'a> { 
    name: &'a str, 
}

这样可以避免没必要的内存拷贝以提升性能，但是吧，很多人可能看到生命周期就头疼，所以这里选择了效率不那么高的方式，也就是直接使用String类型。

模板属性

askama提供了一些可选的属性用于配置模板的一些行为，属性名如下

  • path，比如template(path = "foo.html")), 通过该属性指定使用的模板文件
  • source， 比如template(source = "{{ foo }}"), 直接使用字面值定义的模板内容，该属性需要配合ext属性一起使用。
  • ext，比如template(source = "{{ foo }}", ext="txt"), 指定模板的扩展名, 不同的扩展名代表不一样的内容，比如html就需要额外的转义以避免XSS攻击, 该属性不能和path属性一起使用。
  • print，比如template(print = "code"))，用于debug时使用，在运行的时候会打印宏生成的代码code, 或者语法树ast。
  • escape，比如template(escape = "none")), 可以通过配置none来禁用转义。
  • syntax，比如template(syntax = "foo")),  指定要使用的语法配置, 如果你想自定义一种语法的话。

配置

在上一节有一个可能不太容易理解的配置，那就是syntax，它的选项主要来源于askama提供的语法配置选项，我们可以在根目录创建一个askama.toml文件, askama在编译的时候会读取这个文件，下面是一个官方示例:

      
      [general]
default_syntax = "foo"

[[syntax]]
name = "foo"
block_start = "%{"
comment_start = "#{"
expr_end = "^^"

[[syntax]]
name = "bar"
block_start = "%%"
block_end = "%%"
comment_start = "%#"
expr_start = "%{"

为啥要配置一套额外的奇怪的语法?

比如上面的expr_start=%{, 而默认的是{{, 这里的应用场景其实主要是用模板渲染模板的时候比较有用(嗯, 奇怪的需求)，比如使用rust渲染Python或者golang的模板, 后两者也是使用的一样的语法即{{。

如果你使用过helm可能会理解这个需求，假设需求是根据需求创建对应的helm模板(chart), helm里面其实会用到Golang的模板语法, 如果你想做一个渲染这种模板的需求，那么你可能就需要定义一套区别于Golang渲染语法的askama语法了。

除此之外我们还可以配置模板文件读取的位置，如果我们不喜欢templates这个目录名的话。

      [general]
# 默认情况是templates
dirs = ["tpls"]

语法

就像开头所说的, askama算得上是Jinja的Rust版实现，所以语法几乎一致, 如果你会Jinja的语法几乎就懂askama的语法。

变量

这个比较简单，name是模板结构体struct中定义的字段，askama对于要渲染的变量类型的要求是其实现了Display这个trait。

      {{ name }}


赋值


在渲染的上下文中创建一个新的变量。


        
        {% let len = name.len() %}
name length is {{ len }}

过滤器


对变量或者字面值做一个额外的处理，更多的内置的过滤器可以参考: https://djc.github.io/askama/filters.html


        
        {{ "hello"|capitalize }} {{ name|capitalize }}

上面这部分的输出如下


        
        Hello Youerning.top

要注意过滤|的两端不要有空格。


空格控制


渲染的时候可以选择是否将模板中的空格消除掉，比如


        
        >>  {{ name }}  <<

的渲染结果是>> youerning.top <<


但是我们可以选择消除两边的空格，比如


        
        >>  {{- name -}}  <<

的渲染结果是>>youerning.top<<，可以看到, 模板语法把到非空字符之间的空格消除了，这种消除对于那些对空格敏感的格式很有用，比如yaml，又或者渲染的结果需要美化之类的。


上面的例子是为了简单起见，一般来说消除的是控制结构比如if和for之类的语句的空格，比如下面这样。


        
        {% if foo %}
  {{- bar -}}
{% else if -%}
  nothing
{%- endif %}

askama一共支持三种空格控制的语法，第二个第三个没用过，这里直接复制的官方说明。



  2. Suppress (-)
  3. Minimize (~)
  4. Preserve (+)

函数


askama支持三种形式的函数调用



  • 模板的字段
  • 静态函数
  • Struct/Trait 的函数实现, 也就是impl xxx这样定义的函数

官方示例如下


      
      #[derive(Template)]
#[template(source = "{{ foo(123) }}", ext = "txt")]
struct MyTemplate {
  foo: fn(u32) -> String,
}

其他的函数定义形式这里就不赘述了。


模板继承


如果是做web开发，那么对继承应该不陌生，页面之间总是会存在可以复用的情况，所以我们可以将相同的部分抽离出来作为父模板, 其他模板复用父模板的相同部分，这和面向对象的继承差不多。


首先需要一个base.html


      
      <!DOCTYPE html>
<html lang="en">
  <head>
    <title>{% block title %}{{ title }} - My Site{% endblock %}</title>
    {% block head %}{% endblock %}
  </head>
  <body>
    <div id="content">
      {% block content %}<p>Placeholder content</p>{% endblock %}
    </div>
  </body>
</html>

其中{% block content %}{% endblock %}包裹的部分就是我们可以替换的部分。


子模板像下面这样继承即可。


      
      {% extends "base.html" %}

{% block title %}Index{% endblock %}

{% block head %}
  <style>
  </style>
{% endblock %}

{% block content %}
  <h1>Index</h1>
  <p>Hello, world!</p>
  {% call super() %}
{% endblock %}

除了继承，我们可以使用include指令来渲染一些通用的部分，比如:


      
      {% for i in iter %}
  {% include "item.html" %}
{% endfor %}

而item.html的内容如下:


      
      * Item: {{ i }}

控制结构


之所以要使用模板引擎而不是format!宏的一个很大的原因在于模板引擎支持控制结构，也就是循环和判断。


for循环 


      
      {% for char in name.chars() %}
  -{{loop.index}}: {{ char|upper }}
{% endfor %}

if判断 


      
      {% if name == 0 %}
  youerning.top
{% else if name.len() == 1 %}
  {{ name | upper }}
{% else %}
  {{ name }}
{% endif %}

表达式 


      
      {{ 3 * 4 / 2 }}
{{ 26 / 2 % 7 }}


要注意表达式不要出现递归



注释 


      
      {# A Comment #}

结合web框架axum使用


最后来一个与axum一起使用的例子作为结尾吧。


rust代码如下:


      
      
use axum::{
    http::StatusCode, response::{Html, IntoResponse, Response}, routing::get, Router
};
use askama::Template;

#[derive(Template, Default)]
#[template(path = "index.html")]
struct Index{
    title: String,
    content: String,
}

struct TemplateResponse<T>(T);

impl<T> IntoResponse for TemplateResponse<T>
where
    T: Template,
{
    fn into_response(self) -> Response {
        match self.0.render() {
            Ok(html) => Html(html).into_response(),
            Err(err) => (
                StatusCode::INTERNAL_SERVER_ERROR,
                format!("Failed to render template. Error: {err}"),
            )
                .into_response(),
        }
    }
}


pub async fn index() -> impl IntoResponse {
    TemplateResponse(Index{
        title: "askama快速入门".into(),
        content: "做人最重要的就是开心啦.".into(),
    })
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/", get(index));

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    println!("服务监听在 127.0.0.1:3000");
    axum::serve(listener, app).await.unwrap();
}

index.html的内容如下:


      
      <!DOCTYPE html>
<html lang="en">
  <head>
    <title>{{ title }} - youerning.top</title>
  </head>
  <body>
    <div id="content" style="text-align: center;">
      {{content}}
    </div>
  </body>
</html>

总结


每门编程语言几乎都有模板引擎的，其实差别不大，但是根据语言特性的不同可能会稍稍改动，比如askama还能在模板中使用match语句, 以及变量赋值的时候需要在前面加个let, 这些都是编程语言特性带来的。


参考链接



  • https://docs.rs/askama/latest/askama/#the-template-attribute
  • https://djc.github.io/askama/askama.html

浏览 24
点赞
评论
收藏
分享

手机扫一扫分享

分享
举报
评论
图片
表情
推荐
Askama模板渲染引擎
Askama 实现了一个基于 Jinja 的模板渲染引擎。它在编译时基于一个用户定义的结构来保持模板
Askama模板渲染引擎
Askama实现了一个基于Jinja的模板渲染引擎。它在编译时基于一个用户定义的结构来保持模板的上下文，从你的模板中生成Rust代码。功能亮点使用熟悉、易于使用的语法构建模板受益于Rust类型系统提供
费尔模板引擎PHP模板引擎
费尔模板引擎是一个基于PHP的高效的PHP模板引擎，主要对于PHP程序的方面快速开发而设计,这意味着
费尔模板引擎PHP模板引擎
费尔模板引擎是一个基于PHP的高效的PHP模板引擎，主要对于PHP程序的方面快速开发而设计,这意味着PHP代码与HTML是分开的,让程序员有足够的空间发挥编写程序,让网页设计师轻松维护模板代码，而不需
JSPTemplatesJSP模板引擎
JSPTemplates 是一个允许开发者写JSP页的模板引擎，非常类似于Sun API。页面的输出
CoffeeKupNode.js 模板引擎
CoffeeKup 是一个 Node.js 的模板引擎，可让你使用 100% 的 CoffeeScr
pongo2Go 模板引擎
pongo 2 是一个 Go 语言的模板引擎，其语法与 Django 模板类似，并且完全兼容 Dja
ZipscriptJava 模板引擎
Zipscript 是一个 Java 的模板引擎，号称集成了Velocity和FreeMarker的
PHPnow模板引擎
PHPnow是一个基于PHP的高效的PHP模板引擎，主要对于PHP程序的方面快速开发而设计,这意味着
MustacheJavaScript模板引擎
基于javascript 实现的模板引擎,类似于 Microsoft’s jQuery templa
点赞
评论
收藏
分享

手机扫一扫分享

分享
举报