【Rust编程】Actix-web 开发环境搭建完整教程

优质文章学习记录

— 11 min read
【Rust编程】Actix-web 开发环境搭建完整教程

Actix-web 开发环境搭建完整教程

Actix-web 开发环境搭建完整教程

本教程将从零开始，手把手教你搭建 Actix-web 开发环境，涵盖 Rust 安装、项目创建、依赖配置、代码编写、运行调试、测试部署 全流程，适合 Rust 新手和有经验的开发者。

一、前置准备：安装 Rust 工具链

Actix-web 基于 Rust 语言，需先安装 Rust 工具链（含编译器 rustc、包管理器 cargo、构建工具等）。

1. 安装 Rustup（Rust 版本管理器）

打开终端，执行以下命令（根据系统选择）：

# Linux/macOScurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs |sh# Windows# 下载 rustup-init.exe 从 https://rustup.rs/，双击运行并按提示安装

安装过程中选择 默认配置（直接按 Enter），安装完成后重启终端。

2. 验证安装

执行以下命令，输出版本号即成功：

rustc --version # 示例：rustc 1.74.1 (a28077b28 2023-12-04) cargo --version # 示例：cargo 1.74.1 (ecb9851af 2023-10-18)

3. 配置国内镜像源（加速依赖下载）

国内用户建议配置清华/中科大镜像，编辑 ~/.cargo/config 文件（Windows 路径：C:\Users\<用户名>\.cargo\config）：

[source.crates-io] registry = "https://github.com/rust-lang/crates.io-index" replace-with = 'tuna' # 使用清华镜像 [source.tuna] registry = "https://mirrors.tuna.tsinghua.edu.cn/git/crates.io-index.git" [net] git-fetch-with-cli = true # 使用系统 git 下载（避免 SSL 问题）

4. 安装开发工具

安装 Rust 官方推荐的代码格式化、语法检查和 VS Code 扩展：

# 安装 rustfmt（代码格式化）和 clippy（静态检查） rustup component add rustfmt clippy # 安装 VS Code 扩展（如果用 VS Code） code --install-extension rust-lang.rust-analyzer # Rust 语言服务器 code --install-extension serayuzgur.crates # 依赖管理 code --install-extension bungcip.better-toml # TOML 文件支持

二、创建 Actix-web 项目

1. 创建项目骨架

使用 cargo new 创建二进制项目（可执行程序）：

cargo new actix-demo --bin # --bin 表示创建可执行项目（默认）cd actix-demo # 进入项目目录

项目结构如下：

actix-demo/ ├── Cargo.toml # 项目依赖和配置 └── src/ └── main.rs # 程序入口

2. 添加 Actix-web 依赖

编辑 Cargo.toml，添加 Actix-web 及相关依赖：

[package] name = "actix-demo" version = "0.1.0" edition = "2021" # Rust 2021 版本 [dependencies] actix-web = "4.4" # Actix-web 核心库（最新稳定版 4.4.x） actix-rt = "2.9" # Actix 异步运行时（必须依赖） env_logger = "0.10" # 环境变量日志配置 log = "0.4" # 日志门面（统一日志接口） serde = { version = "1.0", features = ["derive"] } # JSON 序列化/反序列化 dotenv = "0.15" # 加载 .env 环境变量文件 chrono = { version = "0.4", features = ["serde"] } # 时间处理（可选，示例中用）
版本说明：actix-web = "4.4" 表示兼容 4.4.x 系列最新版，可通过 https://crates.io/crates/actix-web 查看最新版本。

三、编写第一个 Actix-web 应用

1. 基础代码（src/main.rs）

实现一个包含 健康检查、首页、JSON API 的简单服务：

useactix_web::{ get,// 路由宏：GET 请求App,// 应用构建器HttpResponse,// 响应类型HttpServer,// HTTP 服务器Responder,// 响应 trait web,// 工具模块（数据提取、JSON 等）};usechrono::Utc;// 时间处理（需添加 chrono 依赖）usedotenv::dotenv;uselog::info;useserde::Serialize;usestd::env;// 1. 健康检查端点（GET /health）#[get("/health")]asyncfnhealth_check()->implResponder{HttpResponse::Ok().body("OK")// 返回 200 OK + 文本 "OK"}// 2. 首页端点（GET /）#[get("/")]asyncfnindex()->implResponder{HttpResponse::Ok().body("Welcome to Actix-web! 🚀")}// 3. JSON API 端点（GET /api/time）#[derive(Serialize)]// 自动实现 JSON 序列化structTimeResponse{ timestamp:i64,// 时间戳（秒） datetime:String,// 格式化时间}#[get("/api/time")]asyncfnget_current_time()->implResponder{let now =Utc::now();HttpResponse::Ok().json(TimeResponse{ timestamp: now.timestamp(), datetime: now.format("%Y-%m-%d %H:%M:%S").to_string(),})}#[actix_web::main]// Actix 异步运行时入口（等价于 #[tokio::main]）asyncfnmain()->std::io::Result<()>{// 加载 .env 文件（若存在）dotenv().ok();// 初始化日志（从环境变量 RUST_LOG 读取级别，默认 info）env_logger::init_from_env(env_logger::Env::new().default_filter_or("info"));// 从环境变量读取端口（默认 8080）let port =env::var("PORT").unwrap_or_else(|_|"8080".to_string());let bind_addr =format!("0.0.0.0:{}", port);// 绑定所有网卡info!("Starting Actix-web server at http://{}", bind_addr);// 启动 HTTP 服务器HttpServer::new(||{App::new()// 创建应用实例.service(health_check)// 注册健康检查路由.service(index)// 注册首页路由.service(get_current_time)// 注册 JSON API 路由}).bind(bind_addr)?// 绑定地址（失败返回错误）.run()// 运行服务器.await// 等待异步完成}

2. 配置环境变量（可选）

创建 .env 文件（项目根目录），自定义端口和日志级别：

# .env 文件 PORT=8080 # 服务端口（默认 8080） RUST_LOG=actix_web=debug # 日志级别：debug（显示详细请求日志）

四、运行与测试服务

1. 启动开发服务器

在项目根目录执行：

cargo run

首次运行会下载依赖（需几分钟，国内镜像加速后更快），成功后输出：

[INFO actix_demo] Starting Actix-web server at http://0.0.0.0:8080

2. 测试端点

打开新终端，用 curl 或浏览器测试：

# 1. 首页curl http://localhost:8080/ # 输出：Welcome to Actix-web! 🚀# 2. 健康检查curl http://localhost:8080/health # 输出：OK# 3. JSON API（返回当前时间和时间戳）curl http://localhost:8080/api/time # 输出：{"timestamp":1717234567,"datetime":"2024-06-01 12:36:07"}

3. 热重载开发（提高效率）

安装 cargo-watch 实现代码修改后自动重启：

cargo install cargo-watch # 安装 cargo watch -x run # 启动热重载（修改代码后自动重启服务）

五、高级配置（实战必备）

1. 添加中间件（日志、压缩、跨域）

Actix-web 中间件用于处理通用逻辑（如日志、认证、CORS），示例添加 日志中间件 和 响应压缩中间件：

useactix_web::middleware::{Compress,Logger};// 导入中间件#[actix_web::main]asyncfnmain()->std::io::Result<()>{// ...（省略前面的初始化代码）HttpServer::new(||{App::new().wrap(Logger::default())// 日志中间件（记录请求方法、路径、状态码）.wrap(Compress::default())// 响应压缩（自动 gzip/deflate）.service(health_check).service(index).service(get_current_time)}).bind(bind_addr)?.run().await}

2. 数据库连接（PostgreSQL + SQLx）

实际项目需连接数据库，以 PostgreSQL + SQLx 为例：

步骤 1：添加依赖（Cargo.toml）
[dependencies] # ... 其他依赖 sqlx = { version = "0.7", features = ["runtime-tokio-native-tls", "postgres", "macros"] } # SQLx 核心 tokio = { version = "1", features = ["full"] } # Tokio 运行时（Actix 依赖）
步骤 2：创建数据库连接池（src/db.rs）
usesqlx::postgres::PgPoolOptions;usestd::time::Duration;/// 数据库连接池类型别名pubtypeDbPool=sqlx::Pool<sqlx::Postgres>;/// 创建数据库连接池pubasyncfncreate_pool(database_url:&str)->Result<DbPool,sqlx::Error>{PgPoolOptions::new().max_connections(5)// 最大连接数.acquire_timeout(Duration::from_secs(3))// 连接超时.connect(database_url).await}
步骤 3：在 main.rs 中集成数据库
moddb;// 导入 db 模块#[actix_web::main]asyncfnmain()->std::io::Result<()>{// ...（省略初始化日志）// 从环境变量读取数据库 URL（示例：postgres://user:pass@localhost/dbname）let database_url =env::var("DATABASE_URL").expect("DATABASE_URL environment variable not set");let pool =db::create_pool(&database_url).await.expect("Failed to create DB pool");HttpServer::new(move||{App::new().app_data(web::Data::new(pool.clone()))// 共享数据库连接池.service(your_db_handler)// 注册需要数据库的路由// ... 其他服务})// ... 绑定地址并运行}

3. HTTPS 配置（生产环境必备）

使用 rustls 配置 HTTPS（需提前准备 SSL 证书）：

步骤 1：添加依赖
[dependencies] # ... 其他依赖 rustls = "0.21" # TLS 实现 rustls-pemfile = "1.0" # PEM 证书解析
步骤 2：加载证书并启动 HTTPS 服务器
userustls::ServerConfig;userustls_pemfile::{certs, pkcs8_private_keys};usestd::fs::File;usestd::io::BufReader;#[actix_web::main]asyncfnmain()->std::io::Result<()>{// ...（省略初始化代码）// 加载 SSL 证书和私钥（示例路径：./cert.pem, ./key.pem）let cert_file =&mutBufReader::new(File::open("cert.pem").unwrap());let key_file =&mutBufReader::new(File::open("key.pem").unwrap());let cert_chain =certs(cert_file).unwrap().into_iter().map(rustls::Certificate).collect();letmut keys =pkcs8_private_keys(key_file).unwrap();let key =rustls::PrivateKey(keys.remove(0));// 配置 TLSlet tls_config =ServerConfig::builder().with_safe_defaults().with_no_client_auth().with_single_cert(cert_chain, key).unwrap();// 启动 HTTPS 服务器（绑定 443 端口）HttpServer::new(||App::new().service(index)).bind_rustls("0.0.0.0:443", tls_config)?.run().await}

六、开发工具与调试

1. VS Code 调试配置

创建 .vscode/launch.json，配置调试入口：

{"version":"0.2.0","configurations":[{"type":"lldb","request":"launch","name":"Debug Actix-web","program":"${workspaceFolder}/target/debug/actix-demo","args":[],"cwd":"${workspaceFolder}","preLaunchTask":"cargo build"// 调试前自动构建}]}

创建 .vscode/tasks.json，配置构建任务：

{"version":"2.0.0","tasks":[{"label":"cargo build","type":"shell","command":"cargo","args":["build"],"problemMatcher":["$rustc"]}]}

2. 单元测试与集成测试

Actix-web 提供 actix_web::test 模块，方便编写测试：

单元测试示例（tests/health_check.rs）
useactix_web::{test, web,App,http::StatusCode};useactix_demo::{health_check, index};// 导入处理函数#[actix_web::test]// 标记为 Actix 测试asyncfntest_health_check(){// 初始化测试服务let app =test::init_service(App::new().service(health_check)).await;// 发送 GET 请求到 /healthlet req =test::TestRequest::get().uri("/health").to_request();let resp =test::call_service(&app, req).await;// 断言：状态码 200，响应体为 "OK"assert_eq!(resp.status(),StatusCode::OK);let body =test::read_body(resp).await;assert_eq!(body,"OK");}

运行测试：

cargo test# 运行所有测试 cargo test test_health_check # 运行指定测试

七、Docker 部署

1. 编写 Dockerfile（多阶段构建）

# 阶段 1：构建依赖和项目 FROM rust:1.74 as builder WORKDIR /app COPY . . RUN apt-get update && apt-get install -y cmake pkg-config libssl-dev # 安装系统依赖 RUN cargo build --release # 编译 Release 版本 # 阶段 2：运行环境（轻量 Debian 镜像） FROM debian:bullseye-slim RUN apt-get update && apt-get install -y libssl-dev ca-certificates && rm -rf /var/lib/apt/lists/* COPY --from=builder /app/target/release/actix-demo /usr/local/bin/ EXPOSE 8080 # 暴露端口 CMD ["actix-demo"] # 启动命令

2. 构建并运行容器

docker build -t actix-demo .# 构建镜像docker run -d -p 8080:8080 --name actix-app actix-demo # 后台运行容器

八、常见问题解决

1. 端口占用

# Linux/macOS：查找占用 8080 端口的进程lsof -i :8080 kill -9 <PID># 终止进程# Windows：查找占用端口netstat -ano | findstr :8080 taskkill /F /PID <PID>

2. 依赖冲突

cargo clean # 清除 target 目录（解决缓存问题） cargo update # 更新依赖到兼容版本 cargo tree # 查看依赖树（排查冲突）

3. 性能调优

  • 调整线程池：HttpServer::workers(n) 设置工作线程数（建议设为 CPU 核心数 × 2）
  • 启用 HTTP/2：.bind_h2c("0.0.0.0:8080") 或 HTTPS 自动支持
  • 静态文件缓存：用 actix-files 中间件处理静态资源，设置 Cache-Control 头

九、学习资源推荐

  1. 官方文档
    • https://actix.rs/docs/
    • https://docs.rs/actix-web/latest/actix_web/
  2. 实战教程
    • https://dev.to/rogertorres/first-steps-with-rust-using-actix-web-3-3-1khh
    • https://zhuanlan.zhihu.com/p/561876345
  3. 示例项目
    • https://github.com/actix/examples
    • https://github.com/emmanuelantico/actix-web-api-example

总结

通过以上步骤，你已完成 Actix-web 开发环境的搭建，并实现了一个包含路由、中间件、日志的基础服务。接下来可深入学习：

  • 数据库集成（Diesel/SQLx）
  • 身份验证（JWT/OAuth2）
  • WebSocket 实时通信
  • 部署到云服务（AWS/GCP）

相关文档

【桌面应用开发】Windows 环境下 Dioxus 桌面应用开发环境搭建
【Rust编程知识】在 Windows 下搭建完整的 Rust 开发环境
【Rust编程】Cargo 工具详解：从基础到高级的完整指南
【开发语言】Rust语言介绍
【知识科普】.toml配置文件说明

Read more

构建机器人集群系统：ROS 2分布式控制实战指南

构建机器人集群系统：ROS 2分布式控制实战指南 【免费下载链接】PX4-AutopilotPX4 Autopilot Software 项目地址: https://gitcode.com/gh_mirrors/px/PX4-Autopilot 本文将系统讲解如何基于ROS 2构建机器人集群系统，涵盖分布式控制技术原理、核心组件架构、快速部署流程及仓储场景应用。通过从零搭建多机器人协同框架，掌握分布式任务调度与异构机器人协作的关键技术，解决多机通信延迟、任务冲突等核心问题，为工业级机器人集群应用提供完整技术方案。 🔥 技术原理实现方案 机器人集群系统通过分布式控制架构实现多智能体协同，核心在于解决三个关键问题：节点间状态一致性、任务动态分配和实时通信保障。与传统集中式控制相比，分布式架构具有更高的容错性和扩展性，单个节点故障不会导致整个系统瘫痪。 分布式控制的核心算法包括： * 基于一致性协议的状态同步（如Raft算法） * 分布式任务分配的匈牙利算法 * 冲突避免的分布式路径规划 图1：机器人集群分布式控制架构示意图，展示状态感知、任务规划、执行控制的分层协作

MCAP ：机器人数据容器的全面实践指南

Outline: MCAP 已形成完整工具链生态： * Foxglove Studio：可视化分析工具 * mcap-cli：跨平台命令行工具 * AWS RoboMaker：原生云存储支持 随着 IEEE 正在制定的 P3196 机器人数据标准，MCAP 正在演进为行业基础架构的重要组成。其设计哲学启示我们：优秀的数据格式应该在存储效率与读取便利间找到平衡，这正是 MCAP 在机器人革命中脱颖而出的关键。 参考资料： 1. https://juejin.cn/post/7508575831791812658 https://getiot.tech/fileformat/mcap/ MCAP ：机器人数据容器的全面实践指南 在机器人和自动驾驶系统开发中，高效存储和处理传感器数据是核心挑战之一。传统的 ROS bag 格式在面对大规模、多类型数据时逐渐暴露出性能瓶颈，而 MCAP（Modular Container for Asynchronous

探秘：从零解析一块无资料FPGA核心板的逆向工程

1. 缘起：一块神秘的“黑盒子”板卡 最近天气热得让人提不起劲，手头几本讲阵列信号处理和统计信号的大部头书，翻了几页就丢在一边吃灰了。百无聊赖刷手机时，在某二手平台上看到一块拆机的FPGA核心板，价格相当诱人。卖家描述很简单，就说是从旧设备上拆下来的，没有任何资料——没有原理图，没有管脚定义，甚至连芯片型号都只给了一个模糊的“可能是Cyclone IV”。这种“三无”板子对大多数人来说就是块废料，但对我这种喜欢折腾硬件、享受“破译”过程的人来说，却充满了吸引力。跟卖家简单确认了板子成色和来源，没多犹豫就下单了。 板子到手后，看着这块巴掌大小、布满了密密麻麻元件和过孔的绿色板卡，我仿佛拿到了一块需要解密的“黑盒子”。它的价值不在于它本身，而在于我们能否将它从“未知”变为“已知”。这就是硬件逆向工程的魅力所在：在没有任何官方文档支持的情况下，仅凭观察、测量和逻辑推理，让一块沉默的板卡重新“开口说话”，告诉你它的所有秘密。这个过程就像侦探破案，每一个焊点、每一条走线、每一个器件都是线索。
论文阅读|ArxiV 2025|大模型微调综述|A Survey on Federated Fine-Tuning of Large Language Models

论文阅读|ArxiV 2025|大模型微调综述|A Survey on Federated Fine-Tuning of Large Language Models

论文地址：https://arxiv.org/pdf/2503.12016 相关最新研究动态：https://github.com/Chen-Yang-Liu/Awesome-RS-SpatioTemporal-VLMs 文章目录 * 0.综述结构 * 1.引言 * 2. 背景 * 2.1 大型语言模型 * 2.2 大型语言模型的训练 * 2.3 联邦微调 * 3. 挑战 * 3.1 通信开销 * 3.2 数据异质性 * 3.3 内存墙 * 3.4 计算开销 * 4. 大语言模型与时序图像的融合 * 4.1 基于低秩适应（LoRA）的微调