模块系统与代码组织

// src/main.rs —— 700 行之后的样子（节选）
fn parse_args() -> Args { /* ... */ }
fn read_log(path: &str) -> Vec<LogLine> { /* ... */ }
fn parse_line(line: &str) -> Option<LogLine> { /* ... */ }
fn count_by_level(lines: &[LogLine]) -> HashMap<String, usize> { /* ... */ }
fn render_report(counts: &HashMap<String, usize>) -> String { /* ... */ }
// 还有 TestRecord、parse_test_line、count_test_results……测试数据相关的函数也挤在这里

struct LogLine { level: String, message: String }
struct Args { path: String, verbose: bool }

fn main() {
    let args = parse_args();
    let lines = read_log(&args.path);
    let counts = count_by_level(&lines);
    println!("{}", render_report(&counts));
}

logtool/                  <- 包（package）
├── Cargo.toml
└── src/
    ├── main.rs           <- 二进制 crate 的根（crate root）
    ├── args.rs           <- 模块
    ├── parse.rs          <- 模块
    └── report.rs         <- 模块

// src/main.rs
mod args;       // 告诉编译器：去读 src/args.rs，作为名为 args 的模块
mod parse;      // 读 src/parse.rs
mod report;     // 读 src/report.rs

fn main() {
    let a = args::parse();
    let lines = parse::read_file(&a.path);
    report::print(&lines);
}

// src/args.rs —— 模块文件内部无需再写 mod args
pub struct Args {
    pub path: String,
    pub verbose: bool,
}

pub fn parse() -> Args {
    Args {
        path: std::env::args().nth(1).unwrap_or_else(|| "app.log".into()),
        verbose: false,
    }
}

crate（根：main.rs 或 lib.rs）
├── args
├── parse
│   └── tests        （parse.rs 里 mod tests { }）
└── report

// src/parse.rs
use crate::args::Args;        // crate:: 从 crate 根出发（绝对路径）

pub fn read_file(path: &str) -> Vec<String> {
    std::fs::read_to_string(path)
        .unwrap_or_default()
        .lines()
        .map(|l| l.to_string())
        .collect()
}

mod tests {
    use super::*;             // super:: 从父模块出发（相对路径）——tests 的父是 parse

    #[test]
    fn read_empty() {
        let v = super::read_file("nonexistent.log");
        assert!(v.is_empty());
    }
}

src/
├── parse.rs            <- mod parse 本体：声明、公共 API
└── parse/
    └── tests.rs        <- 子模块文件

// src/parse.rs
pub struct LogLine {
    pub level: String,      // 外部可读写字段
    message: String,        // 私有字段：外部只能经方法访问
}

impl LogLine {
    pub fn new(level: &str, message: &str) -> Self {
        LogLine { level: level.into(), message: message.into() }
    }
    pub fn message(&self) -> &str {
        &self.message
    }
}

pub(crate) fn internal_normalize(s: &str) -> String { s.trim().to_lowercase() }
pub(super) fn helper_for_parent() {}

use crate::parse::LogLine;              // 引入类型本体
use std::collections::HashMap;          // 引入标准库类型
use std::io::Write as IoWrite;          // 改名避免冲突

// 函数：引入到父模块，调用时带模块名——来源一目了然
use crate::parse;                       // 然后写 parse::read_file(..)

// 结构体/枚举：直接引入本体——构造时写全名太啰嗦
use crate::parse::LogLine;              // 然后写 LogLine::new(..)

// trait：必须引入本体（否则方法不可见）
use std::io::Write;                     // 然后才能 file.write_all(..)

// 嵌套写法合并同前缀引入（rustfmt 会自动整理成这种形态）
use std::collections::{HashMap, HashSet};
use std::io::{self, Write};            // io 本体 + io::Write 一起拿

// glob：引一个模块的全部公开项
use crate::parse::tests::*;

logtool/
├── Cargo.toml
└── src/
    ├── lib.rs           <- 库 crate：全部可复用逻辑的根
    ├── main.rs          <- 二进制 crate：只有入口几行
    ├── args.rs          <- 模块，属于 lib crate
    ├── parse.rs
    └── report.rs

// src/lib.rs —— 库的根：像 main.rs 一样用 mod 收拢模块
pub mod args;
pub mod parse;
pub mod report;

// src/main.rs —— 二进制的根：把库当依赖用
use logtool::args;      // 注意：库名（Cargo.toml 的 package.name，这里 logtool）
                        // 就是它的 crate 名，同包内的二进制自动依赖这个库

fn main() {
    let a = args::parse();
    let lines = logtool::parse::read_file(&a.path);
    logtool::report::print(&lines);
}

logtool/
├── Cargo.toml
└── src/
    ├── lib.rs
    ├── main.rs
    ├── args.rs
    ├── parse.rs
    └── report.rs

// src/parse.rs
use std::collections::HashMap;

pub struct LogLine {
    pub level: String,
    pub message: String,
}

pub fn parse_line(line: &str) -> Option<LogLine> {
    let (level, message) = line.split_once(' ')?;
    let level = level.trim_matches(['[', ']']).to_uppercase();
    Some(LogLine { level, message: message.into() })
}

pub fn count_by_level(lines: &[LogLine]) -> HashMap<&str, usize> {
    let mut counts = HashMap::new();
    for l in lines {
        *counts.entry(l.level.as_str()).or_insert(0) += 1;
    }
    counts
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn skips_malformed() {
        assert!(parse_line("没有空格的行").is_none());
    }
}

// src/main.rs
use logtool::{args, parse, report};

fn main() {
    let a = args::parse();
    let lines: Vec<_> = std::fs::read_to_string(&a.path)
        .unwrap_or_else(|e| {
            eprintln!("读文件失败: {e}");
            std::process::exit(1);
        })
        .lines()
        .filter_map(parse::parse_line)
        .collect();
    report::print(&parse::count_by_level(&lines));
}

src/
├── lib.rs
└── game/
    ├── mod.rs            <- game 模块本体（目录式布局的另一形态：小模块直接用 mod.rs）
    ├── character.rs
    ├── map.rs
    └── item/
        ├── mod.rs
        ├── weapon.rs
        └── consumable.rs

// src/game/item/mod.rs
pub mod weapon;
pub mod consumable;

#[derive(Debug)]
pub struct ItemBase {
    pub id: u32,
    pub name: String,
}

impl ItemBase {
    pub fn label(&self) -> String {
        format!("[{}] {}", self.id, self.name)
    }
}

// src/game/item/weapon.rs
use super::ItemBase;              // super = game::item

#[derive(Debug)]
pub struct Weapon {
    pub base: ItemBase,
    pub damage: u32,
}

impl Weapon {
    pub fn attack_text(&self) -> String {
        format!("{} 造成 {} 点伤害", self.base.label(), self.damage)
    }
}

// src/lib.rs
pub mod game;

// 深层类型从 crate 根引用
use crate::game::item::weapon::Weapon;

invboard/
├── Cargo.toml
└── src/
    ├── lib.rs           <- 模型与仓储：两个二进制共用
    ├── model.rs
    ├── store.rs
    ├── main.rs          <- 二进制 1：web 服务
    └── bin/
        └── init_db.rs   <- 二进制 2：cargo run --bin init_db

// src/model.rs
#[derive(Debug, Clone)]
pub struct Sku {
    pub code: String,
    pub qty: i64,
}

// src/store.rs
use crate::model::Sku;

pub struct Store {
    rows: Vec<Sku>,
}

impl Store {
    pub fn in_memory() -> Self {
        Store { rows: Vec::new() }
    }
    pub fn upsert(&mut self, sku: Sku) {
        match self.rows.iter_mut().find(|s| s.code == sku.code) {
            Some(existing) => existing.qty = sku.qty,
            None => self.rows.push(sku),
        }
    }
    pub fn all(&self) -> &[Sku] {
        &self.rows
    }
}

// src/lib.rs
pub mod model;
pub mod store;

// src/main.rs —— web 服务入口
use invboard::store::Store;

fn main() {
    let mut store = Store::in_memory();
    // 真实项目这里接 axum 路由（见 140 篇歌曲 API）
    store.upsert(invboard::model::Sku { code: "A-1".into(), qty: 10 });
    for s in store.all() {
        println!("{s:?}");
    }
}

// src/bin/init_db.rs —— 自动成为第二个二进制
use invboard::store::Store;

fn main() {
    let mut store = Store::in_memory();
    store.upsert(invboard::model::Sku { code: "A-1".into(), qty: 0 });
    println!("初始数据就绪");
}

// 起点单文件：src/main.rs
struct Song {
    title: String,
    plays: u32,
}

fn total_plays(songs: &[Song]) -> u32 {
    songs.iter().map(|s| s.plays).sum()
}

fn top_song(songs: &[Song]) -> Option<&Song> {
    songs.iter().max_by_key(|s| s.plays)
}

fn main() {
    let songs = vec![
        Song { title: "星屑".into(), plays: 1200 },
        Song { title: "初雪".into(), plays: 980 },
    ];
    println!("总播放 {}", total_plays(&songs));
    if let Some(s) = top_song(&songs) {
        println!("最热 {}", s.title);
    }
}