本文正在参加「金石方案 . 分割6万现金大奖」 标签：金石方案

摘要

quick-start-rs（quick start a rust project）是用于快速创立一个 rust 项目的脚手架/模板。

  • 标题：为自己量身打造一个 Rust 项目模板/脚手架
  • 深度参阅 Rust Code Quick Start
  • 文章来自 suhanyujie
  • Tags: Rust, utils, quick start, project template，脚手架

正文

当你心血来潮，想用 Rust 写一个小东西时，或许你能够直接运用 cargo new pro1001 之类的指令进行快速创立，但这样你需求做一些前置准备工作，比方：创立 utils crate、过错处理等等。现在或许你能够有更好的办法 —— quick-start-rs，当然，本文只是抛砖引玉，提供一个思路，你完全能够依据自己的需求定制自己的“quick-start-rs”。此外，本文也是参阅 Rust Code Quick Start 撰写的。

本文需求你现已了解运用 VSCode + RA 进行开发 rust 项目开发。

创立项目

当然，从 0 到 1，咱们仍是运用 cargo new quit-start-rs 创立项目，并进入项目目录。

$ cargo new quit-start-rs
$ cd quit-start-rs
.
├── Cargo.lock
├── Cargo.toml
├── README.md
├── src
│  └── main.rs
└── target

utils crate

写项目时，经常会用到所谓的 utils 东西包，其中可能会包罗万象，如字符串处理、加解密，以及一些 helper 办法。有一个快捷办法，直接在 main.rs 顶部参加 mod utils：

mod utils; // <- New
fn main() {
    println!("Hello, world!");
}

此刻 utils crate 尚未被创立和声明，咱们只需将光标放置在报错处，按快捷键 alt + Enter（或许点击小灯泡）：

为自己量身打造一个 Rust 项目模板/脚手架

此刻 RA 会帮你创立好对应的目录和文件：

.
├── Cargo.lock
├── Cargo.toml
├── README.md
├── src
│  ├── main.rs
│  └── utils        //  <- New
│     └── mod.rs
└── target

此刻就能直接在 ./src/utils/mod.rs 文件中编写东西函数。假如还需细分，能够在 src/utils 目录下继续创立文件或目录，用于更详细的模块划分。

过错处理

用 Rust 编写东西或项目时，过错处理是不行短少的东西，随着项目的添加，引进其他第三方 crate，或有各式各样的过错类型，为了在你的项目中一致这些过错，咱们能够用到 thiserror。所以咱们能够将其参加的项目模板中：

[dependencies]
thiserror = "1"

在 main.rs 文件顶部，添加 mod errors;，然后依据“灯泡”提示，直接创立文件：

.
├── Cargo.lock
├── Cargo.toml
├── README.md
├── src
│  ├── errors.rs  // <- New
│  ├── main.rs
│  └── utils
│     └── mod.rs
└── target

然后在其中声明你自己项目的过错类型：

#[derive(thiserror::Error, Debug)]
pub enum Error {
    #[error("Generic {0}")]
    Generic(String),
    // // 例如将标准库中的 io error 一致为你界说的过错类型。以此类推，你能够将其他库中的过错一致为你声明的过错类型。
    #[error(transparent)]
    IO(#[from] std::io::Error), 
}

prelude

每个项目中都能够依据需求定制化地参加要引进的界说或许库，咱们能够将这种预引进独立到一个文件中 prelude.rs。仍是相同的办法，在 main.rs 文件顶部，添加 mod prelude;，然后依据“灯泡”提示，直接创立文件：

.
├── Cargo.lock
├── Cargo.toml
├── README.md
├── src
│  ├── errors.rs 
│  ├── main.rs  
│  ├── prelude.rs   // <- New
│  └── utils
│     └── mod.rs
└── target

能够在文件中参加需求的“预引进”，比方常用的 Result 别名界说：

// prelude.rs
use crate::errors::Error;
pub type Result<T> = std::result::Result<T, Error>;

这样，整个项目中，在需求返回 Result 类型时，直接在函数签名中界说如下的返回值即可（记得要引进 prelude use crate::prelude::*;）：

use crate::prelude::*;
pub fn lib1() -> Result<String> {
    Ok("lib1 is called...".into())
}

New Type 模式

New Type 在 Rust 中是一种惯用法，能够将一个类型进行包装。运用它的含义能够参阅 Rust 言语圣经中：

  • 为外部类型完结 trait
  • 更好的可读性
  • 躲藏内部细节

根据此，咱们能够为该项目完结一个通用的 wrapper 类型，使其在你需求的时分，能够为你所运用：

// prelude.rs
pub struct W<T>(pub T);

示例 —— 读取目录下的文件

为了运用更好的理解，这儿运用一个示例，读取指定目录下的文件列表。在一般情况下，咱们能够运用如下代码完结：

/// read file list in some dir
fn get_files_by_dir(dir: String) -> Result<Vec<String>> {
    let mut list = vec![];
    for entry in fs::read_dir(dir)?.filter_map(|item| item.ok()) {
        let entry = entry
            .path()
            .to_str()
            .map(String::from)
            .ok_or_else(|| Error::Generic("Invalid path {entry:?}".into()))?;
        list.push(entry);
    }
    return Ok(list);
}

根据 fs::read_dir() 的迭代器，迭代的结果是 DirEntry，咱们需求将其转换为 String 类型，咱们能够将 DirEntry 用 W<T>(pub T) 包装一下，并为 W 类型完结 TryFrom trait:

// src/utils/dir_entry_from.rs
impl TryFrom<W<&DirEntry>> for String {
    type Error = Error;
    fn try_from(value: W<&DirEntry>) -> Result<String> {
        value
            .0
            .path()
            .to_str()
            .map(String::from)
            .ok_or_else(|| Error::Generic(format!("Invalid path: {:?}", value.0)))
    }
}

此刻，get_files_by_dir 函数的完结就会简略干净许多：

fn get_files_by_dir(dir: String) -> Result<Vec<String>> {
    let mut list = vec![];
    for entry in fs::read_dir(dir)?.filter_map(|item| item.ok()) {
        let entry: String = W(&entry).try_into()?;
        list.push(entry);
    }
    return Ok(list);
}

此刻可能会有同学问，为啥不直接为 DirEntry 完结 TryFrom trait，而非要用 W 类型包装一下？

首要原因是 Rust 中存在一种“孤儿规矩”（orphan rule）导致，因为它，咱们不能为非本地类型完结非本地的 trait，在这儿，DirEntry 是标准库中的类型，TryFrom 也是标准库中的 trait，因而咱们需求将 DirEntry 包装成一种新的本地类型 —— 即用 W<pub T> 对其进行包装，从而完结 TryFrom trait。

cargo generate

完结以上过程后，你的项目模板根本成形，此刻能够提交到 Github，然后根据这个库房进行新项目的创立。根据模板创立新项目还需求一个东西 —— cargo generate，假如还没有装置，能够运用 cargo install cargo-generate 进行装置。

装置完结后，能够运用指令：cargo generate --git https://github.com/suhanyujie/quick-start-rs.git 进行拉取。

cargo-generate 默认是从 Github 上拉去库房模板的，因而能够运用简短一点的办法：

cargo generate suhanyujie/quick-start-rs

然后依照指令行的提示，输入新项目名称即可生成（例如这儿我输入的项目名是 demo1）：

$  cargo generate suhanyujie/quick-start-rs
⚠️   Favorite `suhanyujie/quick-start-rs` not found in config, using it as a git repository: https://github.com/suhanyujie/quick-start-rs.git
   Project Name: demo1
   Destination: /some/path/xxx/demo1 ...
   project-name: demo1 ...
   Generating template ...
[ 1/15]   Done: .gitignore
[ 2/15]   Done: Cargo.lock
[ 3/15]   Done: Cargo.toml
[ 4/15]   Done: README.md
[ 7/15]   Done: docs/images
[ 8/15]   Done: docs
[ 9/15]   Done: src/errors.rs
[10/15]   Done: src/main.rs
[11/15]   Done: src/prelude.rs
[12/15]   Done: src/utils/dir_entry_from.rs
[13/15]   Done: src/utils/mod.rs
[14/15]   Done: src/utils
[15/15]   Done: src
   Moving generated files into: `/some/path/xxx/demo1`...
   Initializing a fresh Git repository
✨   Done! New project created /some/path/xxx/demo1

实际上 cargo generate 功用许多，更详细的用法和配置能够参阅官方库房和文档。

结语

好了到这儿，咱们的项目脚手架的搭建和运用根本完结，咱们向其中添加了一些根本的过错界说，东西库，以及预引进功用，能够让你在写从 0 到 1 的项目时，更快地聚焦于项目本身的逻辑，进步效率。假如你觉得有更好的办法办法，欢迎在 issues 中提问题沟通 : )。

参阅

  • 关于根据模板创立新项目能够参阅 rust-github.github.io/
  • Rust Code Quick Start
  • cargo generate