最近在社区里看到一个很有意思的项目标题叫“通过写一个 Markdown 到 HTML 的编译器来学习 Rust”。这个想法本身并不新鲜很多教程都会让你写个计算器、Todo 应用或者简单的 Web 服务器来入门。但“写一个编译器”这个目标听起来就有点不一样了。它不像 Todo 应用那样写完增删改查就结束了也不像 Web 服务器更多是在处理网络和并发。编译器尤其是 Markdown 这种文本转换器它要求你思考的层次更深如何把一段结构化的文本Markdown解析成另一种结构化的文本HTML这个过程天然就包含了词法分析、语法解析、抽象语法树构建和代码生成这几个经典的编译步骤。很多人学 Rust 时会陷入语法细节的泥潭所有权、生命周期、模式匹配、Trait……这些概念固然重要但如果没有一个具体的、有挑战性的项目去承载很容易学完就忘或者感觉“不知道能用 Rust 做什么”。而一个 Markdown 转 HTML 的工具恰好是一个复杂度适中、目标明确、且能完整串联起 Rust 核心特性的练手项目。它不需要你懂复杂的算法但能逼着你去理解字符串处理、枚举和模式匹配、递归数据结构、错误处理甚至是简单的泛型和 Trait 使用。更重要的是当你真正动手去实现时你会发现你学到的不仅仅是 Rust 语法更是一种从问题定义到系统分解再到模块化实现的工程化思维。这篇文章我们就来聊聊如何通过“造轮子”——亲手打造一个 Markdown 到 HTML 的编译器——来真正地、深入地学习 Rust。我会带你走过从零开始的完整思考路径而不仅仅是贴出一份可以运行的代码。1. 为什么是 Markdown 编译器一个被低估的“完美”练手项目在决定用某个项目学习一门语言前我们得先想清楚这个项目能覆盖多少这门语言的核心特性以及它能否带来足够的成就感。一个 Markdown 编译器在这两方面都表现得相当出色。首先从技术覆盖面来看这个项目几乎是为 Rust 量身定做的字符串处理 (str,String): Markdown 是纯文本你需要频繁地切片、拼接、查找和替换。这会让你深刻理解 Rust 中字符串的所有权、借用和切片。枚举 (enum) 和模式匹配 (match): Markdown 的语法元素标题、列表、代码块、加粗、链接等是天然的分类。用enum来定义这些元素再用match来处理不同的情况是 Rust 最优雅、最安全的表达方式。递归数据结构 (struct和Box): 一个文档可以看作是一棵由各种块级元素如段落、列表项和行内元素如加粗文本组成的树。定义这样的抽象语法树AST必然会用到自引用的结构这会引导你接触Box、Rc等智能指针理解 Rust 如何管理复杂数据的所有权。错误处理 (Result,Option): 解析过程中可能会遇到格式错误的 Markdown比如未闭合的代码块。如何优雅地报告错误并尝试恢复或跳过是学习 Rust 错误处理哲学显式、可组合的好机会。迭代器 (Iterator) 和函数式编程: 逐行或逐字符扫描文本非常适合用迭代器来表达。你可以练习使用map,filter,collect,peekable等适配器写出既高效又易读的代码。模块化与测试: 你可以将词法分析分词、语法分析构建 AST、渲染生成 HTML拆分成不同的模块mod。这能练习如何组织 Rust 项目结构并为每个模块编写单元测试和集成测试。其次从成就感与实用性来看目标清晰可见: 输入是.md文件输出是.html文件。你可以立刻用浏览器打开看到成果这种即时反馈非常鼓舞人心。挑战梯度合理: 你可以从实现最简单的功能开始比如解析# 标题逐步增加复杂度支持嵌套列表、代码块高亮、内联 HTML 等。每一步的成功都能带来正向激励。理解底层原理: 用过无数 Markdown 编辑器但你知道一个**加粗**是如何变成strong加粗/strong的吗自己实现一遍你会对日常使用的工具有全新的认识。可无限扩展: 基础版本完成后你可以挑战自己支持 GFMGitHub Flavored Markdown的表格和任务列表集成语法高亮库甚至写一个简单的 HTTP 服务器让它成为一个在线的转换工具。所以选择这个项目你不仅仅是在学习 Rust更是在亲手构建一个理解“编译原理”和“文本处理”的微型实验室。2. 第一步别急着写代码先想清楚“编译”的流程很多教程一上来就让你写struct和enum但如果没有一个清晰的蓝图很容易写着写着就乱了。对于编译器哪怕是微型编译器一个经典的处理流程是原始文本 (Markdown) - 词法分析器 (Lexer) - 令牌流 (Tokens) - 语法分析器 (Parser) - 抽象语法树 (AST) - 代码生成器 (Generator) - 目标代码 (HTML)让我们把这个流程对应到我们的 Markdown 编译器上并思考每个阶段在 Rust 中可能如何实现。2.1 词法分析把文本切成有意义的“单词”词法分析器Lexer的任务是扫描字符流将其组合成一个个有意义的“令牌”Token。对于 Markdown 来说令牌就是语法的最小单元。例如对于文本# 这是一个标题\n\n这是一段**加粗**的文字。Lexer 应该产出类似这样的令牌序列HeadingStart(1),Text(这是一个标题),Newline,Newline,Text(这是一段),BoldStart,Text(加粗),BoldEnd,Text(的文字。)在 Rust 中我们首先需要定义这些令牌的类型。这几乎必然要用到enum。#[derive(Debug, Clone, PartialEq)] pub enum Token { // 块级令牌 HeadingStart(u8), // #, ##, ###u8 表示级别 CodeBlockStart(String), // 后面可能跟语言如 rust CodeBlockEnd, UnorderedListStart, // -, *, OrderedListStart(u64), // 1., 2.u64 表示起始数字 ListItemStart, BlockquoteStart, // HorizontalRule, // --- 或 *** // 行内令牌 Text(String), BoldStart, // ** 或 __ BoldEnd, ItalicStart, // * 或 _ ItalicEnd, CodeStart, // \ CodeEnd, LinkStart, // [ LinkEnd, // ] ImageStart, // ![ ImageEnd, // ] LeftParen, // ( RightParen, // ) // 控制令牌 Newline, // 换行符在 Markdown 中有特殊意义可能结束一个段落 EOF, // 文件结束 }有了Token的定义Lexer 的实现就是一个状态机它逐个字符读取输入根据当前字符和状态决定生成什么令牌。这里非常适合使用Iterator模式让 Lexer 成为一个可以不断产出Token的迭代器。注意Markdown 的 Lexer 比编程语言的简单因为它的“关键字”如#,*通常也是文本内容的一部分。难点在于处理边界情况比如*到底是斜体开始还是普通星号这需要 Lexer 有一定的“前瞻”能力或者将歧义留给 Parser 解决。一个常见的策略是Lexer 只做简单的、无状态的识别复杂的结构由 Parser 通过组合令牌来判定。2.2 语法分析从令牌流到树形结构语法分析器Parser接收来自 Lexer 的令牌流并根据 Markdown 的语法规则将其组织成一棵结构化的树——抽象语法树AST。AST 的节点类型也需要用enum来定义但这次是嵌套的因为一个节点可能包含子节点。#[derive(Debug)] pub enum Node { // 文档根节点包含多个块级元素 Document(VecBlock), // 块级元素 Heading(Level, VecInline), // 级别和行内内容 Paragraph(VecInline), CodeBlock(OptionString, String), // 语言和代码内容 UnorderedList(VecListItem), OrderedList(u64, VecListItem), // 起始数字和列表项 ListItem(VecBlock), // 列表项内可以包含多个块如段落、子列表 Blockquote(VecBlock), HorizontalRule, // 行内元素 Text(String), Bold(VecInline), Italic(VecInline), Code(String), Link(String, String), // 链接文本和 URL Image(String, String), // 替代文本和图片 URL } // 为了方便可以定义一些类型别名 pub type Level u8; pub type Block Node; pub type Inline Node; pub type ListItem Node;Parser 的实现是项目的核心挑战之一。它需要处理嵌套结构如列表中的列表并且要能“前瞻”多个令牌来决定当前的结构。例如连续的两个Newline令牌可能意味着一个段落的结束。一个典型的递归下降 Parser 会有一系列的方法每个方法负责解析一种语法结构parse_document() - Node::Documentparse_block() - OptionBlockparse_heading() - OptionBlockparse_paragraph() - Blockparse_inline() - Inline...Parser 会不断地从 Lexer 迭代器中peek查看下一个令牌或consume消耗当前令牌并根据令牌类型调用相应的方法。2.3 代码生成遍历 AST输出 HTML这是最后一步也相对直观。我们需要为 AST 中的每种Node定义如何将其转换为 HTML 字符串。我们可以为Node实现一个render_html方法或者写一个独立的HtmlRenderer结构体来遍历 AST。impl Node { pub fn render_html(self) - String { match self { Node::Document(children) { let inner: String children.iter().map(|c| c.render_html()).collect(); format!(!DOCTYPE htmlhtmlbody{}/body/html, inner) } Node::Heading(level, content) { let inner: String content.iter().map(|c| c.render_html()).collect(); format!(h{}{}/h{}, level, inner, level) } Node::Paragraph(children) { let inner: String children.iter().map(|c| c.render_html()).collect(); format!(p{}/p, inner) } Node::Bold(children) { let inner: String children.iter().map(|c| c.render_html()).collect(); format!(strong{}/strong, inner) } Node::Text(s) html_escape::escape_text(s).to_string(), // 注意转义 HTML 特殊字符 // ... 处理其他节点类型 _ String::new(), // 简化处理 } } }关键点在输出 HTML 时必须对纯文本内容进行转义如将转成lt;否则会引入安全漏洞XSS或破坏 HTML 结构。可以使用html_escape这类库。至此我们已经从概念上拆解了整个项目。接下来我们进入更具体的 Rust 实现细节和那些容易踩坑的地方。3. 核心实现用 Rust 的强类型系统为编译器建模有了清晰的流程我们就可以开始用 Rust 的特性来优雅地实现它。这一部分我们会看到 Rust 的枚举、模式匹配、迭代器和错误处理如何让编译器代码变得清晰且安全。3.1 设计 Lexer状态机与迭代器的结合Lexer 需要遍历输入字符串。我们可以将其实现为一个结构体内部保存输入字符串的字符迭代器和当前状态。pub struct Lexera { input: std::str::Charsa, // 字符迭代器 current_char: Optionchar, // 当前查看的字符 // 可能还需要一个缓冲区来暂存正在构建的文本令牌 buffer: String, } impla Lexera { pub fn new(input: a str) - Self { let mut chars input.chars(); let current_char chars.next(); // 预读第一个字符 Lexer { input: chars, current_char, buffer: String::new(), } } // 核心方法获取下一个令牌 pub fn next_token(mut self) - OptionToken { self.skip_whitespace_except_newline(); // 跳过空格但保留换行符 let c self.current_char?; // 如果没字符了返回 None match c { # self.parse_heading(), * | - | self.parse_list_or_emphasis(c), self.parse_code(), [ Some(Token::LinkStart), ! self.parse_image(), \n { self.consume_char(); Some(Token::Newline) } // ... 处理其他特殊字符 _ self.parse_text(), // 默认情况是解析普通文本 } } // 辅助方法消费当前字符并预读下一个 fn consume_char(mut self) - Optionchar { let current self.current_char; self.current_char self.input.next(); current } // 解析文本直到遇到特殊字符或换行 fn parse_text(mut self) - OptionToken { self.buffer.clear(); while let Some(c) self.current_char { if is_special_char(c) || c \n { // is_special_char 需要你定义 break; } self.buffer.push(c); self.consume_char(); } if self.buffer.is_empty() { None } else { Some(Token::Text(self.buffer.clone())) } } // ... 其他 parse_xxx 方法 } // 为了让 Lexer 可以用在 for 循环里可以实现 Iterator trait impla Iterator for Lexera { type Item Token; fn next(mut self) - OptionSelf::Item { self.next_token() } }3.2 设计 Parser递归下降与Result类型Parser 会消费 Lexer 产出的令牌流。我们同样可以实现一个Parser结构体内部包装一个PeekableLexer这样我们就可以方便地查看下一个令牌而不消耗它。pub struct Parsera { tokens: std::iter::PeekableLexera, // 可能还需要一些状态比如当前是否在段落内 } impla Parsera { pub fn new(lexer: Lexera) - Self { Parser { tokens: lexer.peekable(), } } pub fn parse_document(mut self) - ResultNode, ParseError { let mut blocks Vec::new(); while self.tokens.peek().is_some() { // 跳过连续的换行符 self.consume_while(|t| t Token::Newline); if let Some(block) self.parse_block()? { blocks.push(block); } } Ok(Node::Document(blocks)) } fn parse_block(mut self) - ResultOptionBlock, ParseError { let token match self.tokens.peek() { Some(t) t, None return Ok(None), }; match token { Token::HeadingStart(_) self.parse_heading().map(Some), Token::UnorderedListStart self.parse_unordered_list().map(Some), Token::CodeBlockStart(_) self.parse_code_block().map(Some), // ... 其他块级元素 _ self.parse_paragraph().map(Some), // 默认按段落处理 } } fn parse_heading(mut self) - ResultBlock, ParseError { // 确认是 HeadingStart 令牌 if let Some(Token::HeadingStart(level)) self.tokens.next() { // 消耗令牌后解析行内内容直到遇到换行或文件结束 let inlines self.parse_inline_until(Token::Newline)?; Ok(Node::Heading(level, inlines)) } else { Err(ParseError::UnexpectedToken) } } fn parse_paragraph(mut self) - ResultBlock, ParseError { let mut inlines Vec::new(); // 持续解析行内元素直到遇到两个连续的换行符或文件结束 while let Some(token) self.tokens.peek() { if *token Token::Newline { // 偷看下一个是不是也是换行符 let mut iter self.tokens.clone(); // 克隆迭代器来偷看 iter.next(); // 跳过当前换行符 if iter.peek() Some(Token::Newline) { // 是连续两个换行段落结束 break; } } // 否则解析一个行内元素 if let Some(inline_node) self.parse_inline()? { inlines.push(inline_node); } } // 消耗掉段落末尾的换行符 self.consume_while(|t| t Token::Newline); Ok(Node::Paragraph(inlines)) } // ... 其他 parse_xxx 方法 }错误处理parse_xxx方法返回ResultT, ParseError。ParseError可以是一个自定义的枚举包含各种错误类型如UnexpectedToken、UnclosedDelimiter等。这强迫调用者处理可能的错误而不是让程序 panic。3.3 渲染与集成组合一切最后我们将所有部分组合起来。主函数可能像这样use std::fs; fn main() - Result(), Boxdyn std::error::Error { // 1. 读取 Markdown 文件 let markdown_input fs::read_to_string(input.md)?; // 2. 词法分析 let lexer Lexer::new(markdown_input); // 3. 语法分析 let mut parser Parser::new(lexer); let ast parser.parse_document()?; // 4. 生成 HTML let html_output ast.render_html(); // 5. 写入文件 fs::write(output.html, html_output)?; println!(转换成功); Ok(()) }4. 从“能跑”到“好用”工程化与进阶思考让一个基础版本运行起来只是第一步。要让这个项目真正具有学习价值和实用价值我们还需要考虑以下几个层面。4.1 处理边缘情况与错误恢复一个健壮的编译器不能因为一点格式问题就崩溃。我们的 Parser 需要有一定的错误恢复能力。未闭合的标记比如**加粗没有闭合。简单的策略是在段落或文档结束时强制闭合所有未闭合的行内标记并记录一个警告或者将其视为普通文本。嵌套冲突Markdown 的嵌套规则有时模糊。例如*italic **bold** italic*是合理的但**bold *italic** bold*则可能产生歧义。CommonMark 等规范有明确定义。实现时可以遵循一个简单规则如“先开始的后结束”或者直接采用 CommonMark 的测试套件来验证。性能考虑对于大文件频繁的字符串克隆clone()可能成为瓶颈。可以考虑使用str切片来引用原始输入而不是到处使用String。但这会使得生命周期管理变得复杂对于学习项目初期使用String换取简单性是值得的。4.2 测试驱动开发Rust 对测试的支持一流。为你的 Lexer、Parser 和 Renderer 编写单元测试是保证代码质量、方便后续重构的最佳实践。#[cfg(test)] mod tests { use super::*; #[test] fn test_lexer_heading() { let input # Hello; let mut lexer Lexer::new(input); assert_eq!(lexer.next(), Some(Token::HeadingStart(1))); assert_eq!(lexer.next(), Some(Token::Text(Hello.to_string()))); assert_eq!(lexer.next(), None); } #[test] fn test_parser_simple_paragraph() { let input Hello world.; let lexer Lexer::new(input); let mut parser Parser::new(lexer); let ast parser.parse_document().unwrap(); // 断言 ast 的结构符合预期 match ast { Node::Document(blocks) { assert_eq!(blocks.len(), 1); if let Node::Paragraph(inlines) blocks[0] { assert_eq!(inlines.len(), 1); if let Node::Text(text) inlines[0] { assert_eq!(text, Hello world.); } else { panic!(Expected Text node); } } else { panic!(Expected Paragraph node); } } } } }你可以从 CommonMark 的官方示例中选取一些标准用例作为集成测试。4.3 扩展功能迈向“真正”的编译器当基础功能稳定后你可以尝试以下扩展它们会带你接触更广泛的 Rust 生态和更复杂的设计模式支持 Front Matter解析 Markdown 文件头部的 YAML 或 TOML 元数据。这会引入对serde_yaml或toml库的使用。集成语法高亮对于代码块使用syntect或tree-sitter库进行语法高亮生成带 CSS 类的 HTML。这会教你如何集成外部 crate 并处理其复杂的 API。开发 CLI 工具使用clap或structopt库构建一个命令行工具支持指定输入/输出文件、自定义模板等选项。构建 Web 服务使用actix-web或warp框架创建一个简单的 HTTP 服务接受 Markdown 文本并返回 HTML。这会涉及异步编程和 Web 开发的基础。编写 IDE 插件虽然更复杂但你可以尝试用 Rust 为 VS Code 等编辑器编写一个 LSPLanguage Server Protocol服务器提供 Markdown 的实时预览或语法检查。4.4 反思与收获你真正学到了什么完成这个项目后回过头看你收获的远不止一份代码。你实践了问题分解将“转换 Markdown”这个大问题拆解为词法、语法、渲染等可解决的小问题。类型驱动设计用enum和struct精确地描述领域模型令牌、AST 节点让非法状态无法表示。错误处理哲学使用Result和自定义错误类型让错误成为 API 的一部分并被强制处理。迭代器模式用Iterator抽象数据流使 Lexer 和 Parser 的接口清晰且可组合。测试的重要性为解析逻辑编写测试确保核心功能的正确性并为重构提供安全保障。这个“轮子”可能性能不如pulldown-cmark功能不如comrak但它的价值在于它完全属于你。你清楚地知道每一行代码为何存在每一个设计决策背后的权衡。这种通过实践获得的、对系统底层运作的理解是任何现成库都无法给予的。所以如果你正在学习 Rust并且已经厌倦了书本上的孤立的例子不妨就从今天开始动手实现你的 Markdown 编译器。从解析一个#号开始一步步构建起你的系统。当你第一次看到自己编写的程序将一篇简单的 Markdown 转换成正确的 HTML 时你会对“编程”和“Rust”有全新的、更坚实的认识。这不仅仅是学习一门语言更是在学习如何思考、如何构建。