1. 总览：Actix Web 的三层结构

• 网络与运行时：基于 tokio（异步 I/O, epoll/kqueue），mio 提供底层事件，actix-rt 封装 runtime。
• 服务与中间件模型（tower-like）：核心是 Service/ServiceFactory/Transform 三套 trait，把 请求管线 组织成“Middleware → Service → Handler”的洋葱模型。
• 路由与提取器层：App/Scope/Resource 管理路由树；FromRequest 为提取器（路径参数、查询、JSON、State、扩展等）提供异步解析。

心智模型：HttpServer 起多个 worker（线程），每个 worker 内维护自己的“服务管线实例”。连接进来 → 解析 HTTP → 经过 中间件栈 → 命中 资源/路由 → 调用 handler → 返回响应（可能是 streaming/分块）。

---

2. 生命周期：一次请求从 socket 到响应

1. Listener 接入
   HttpServer 监听 TCP（可多进程 REUSEPORT），接入后分发给 worker 的事件循环。
2. 协议解析与 Payload
   使用 actix-http 解析 HTTP/1.1（支持 keep-alive）/HTTP/2（需 TLS 支持），构造 ServiceRequest、Payload（请求体流）。
3. 中间件栈（Transform）
   典型如日志、限流、压缩、超时、鉴权。它们是 Service<ServiceRequest> -> Future<Output=ServiceResponse> 的高阶包装。
4. 路由匹配
   App/Scope 维护前缀树，匹配到 Resource，执行对应 handler。
5. 提取器（FromRequest）
   如 Path<T>、Query<T>、Json<T>、Data<T> 等在调用 handler 前异步完成解析/校验。
6. 响应与背压
   HttpResponse 可一次性返回（Body::Bytes）或流式返回（Body::MessageBody 实现，写入端有背压，避免把内存写爆）。
7. 观察与关闭
   中间件记录指标/日志；优雅关闭时，server 停止接收新连接，等待 in-flight 完成。

---

3. 高性能工程基线（可直接用）

Cargo.toml（核心依赖）

[package]
name = "actix_hi_perf"
version = "0.1.0"
edition = "2021"

[dependencies]
actix-web = "4"
actix-http = "3"
actix-service = "2"
actix-web-httpauth = "0.8"      # 可选：Bearer/Basic 认证
bytes = "1"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tracing = "0.1"
tracing-subscriber = { version="0.3", features=["env-filter","fmt","json"] }
time = "0.3"
once_cell = "1"
awc = "3"                       # actix HTTP client（可选）
actix-files = "0.6"             # 静态文件（可选）
# HTTP/2 + TLS（任选其一）
rustls = "0.23"
tokio-rustls = "0.26"
rustls-pemfile = "2"

main.rs（服务骨架 + 常用中间件 + 优雅退出）

use actix_web::{
    dev::{ServiceRequest, ServiceResponse},
    http::header,
    middleware::{Compress, Logger, NormalizePath, TrailingSlash},
    web::{self, Data, Json, Path, Query},
    App, Error, HttpResponse, HttpServer, Responder,
};
use bytes::Bytes;
use serde::{Deserialize, Serialize};
use std::{io, sync::Arc, time::Duration};
use tracing::{info, Level};

#[derive(Clone)]
struct AppState {
    greeting: &'static str,
    // 放只读热路径数据（Arc + 不可变结构）以避免锁
}

#[derive(Deserialize)]
struct HelloPath { name: String }
#[derive(Deserialize)]
struct ListQuery { offset: Option<usize>, limit: Option<usize> }
#[derive(Deserialize, Serialize)]
struct Item { id: u64, title: String }

// ------- 自定义中间件（超时/限流示例：简化版） -------
use actix_service::{Service, Transform};
use futures_util::future::{ready, LocalBoxFuture, Ready};
use std::task::{Context, Poll};

struct TimeoutLayer { dur: Duration }
impl<S, B> Transform<S, ServiceRequest> for TimeoutLayer
where
    S: Service<ServiceRequest, Response=ServiceResponse<B>, Error=Error> + 'static,
    S::Future: 'static,
    B: 'static,
{
    type Response = ServiceResponse<B>;
    type Error = Error;
    type Transform = TimeoutMiddleware<S>;
    type InitError = ();
    type Future = Ready<Result<Self::Transform, Self::InitError>>;
    fn new_transform(&self, service: S) -> Self::Future {
        ready(Ok(TimeoutMiddleware { service, dur: self.dur }))
    }
}
struct TimeoutMiddleware<S> { service: S, dur: Duration }
impl<S, B> Service<ServiceRequest> for TimeoutMiddleware<S>
where
    S: Service<ServiceRequest, Response=ServiceResponse<B>, Error=Error> + 'static,
    S::Future: 'static,
    B: 'static,
{
    type Response = ServiceResponse<B>;
    type Error = Error;
    type Future = LocalBoxFuture<'static, Result<Self::Response, Self::Error>>;
    fn poll_ready(&self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
        self.service.poll_ready(cx)
    }
    fn call(&self, req: ServiceRequest) -> Self::Future {
        let fut = self.service.call(req);
        let dur = self.dur;
        Box::pin(async move {
            tokio::select! {
                res = fut => res,
                _ = tokio::time::sleep(dur) => {
                    // 统一超时响应
                    Ok(ServiceResponse::new(
                        // 这里没有原始 req，只能返回构造的响应；更严格可提前 clone 情况
                        actix_web::HttpRequest::default(),
                        HttpResponse::GatewayTimeout()
                            .insert_header((header::CONTENT_TYPE, "application/json"))
                            .body(r#"{"code":"TIMEOUT","msg":"upstream timeout"}"#),
                    ))
                }
            }
        })
    }
}

// ------- 业务 Handler -------
async fn healthz() -> impl Responder { "ok" }

async fn hello(path: Path<HelloPath>, state: Data<AppState>) -> impl Responder {
    HttpResponse::Ok()
        .insert_header((header::SERVER, "actix"))
        .body(format!("{}, {}!", state.greeting, path.name))
}

async fn list_items(q: Query<ListQuery>) -> Result<Json<Vec<Item>>, Error> {
    let offset = q.offset.unwrap_or(0);
    let limit = q.limit.unwrap_or(10).min(100);
    // 假数据：真实场景中注意使用 Bytes/小对象池减少分配
    let data = (0..limit).map(|i| Item {
        id: (offset + i) as u64,
        title: format!("item-{}", offset + i),
    }).collect::<Vec<_>>();
    Ok(Json(data))
}

/// 零拷贝友好：直接返回 Bytes
async fn bytes_demo() -> impl Responder {
    HttpResponse::Ok()
        .insert_header((header::CONTENT_TYPE, "application/octet-stream"))
        .body(Bytes::from_static(b"0123456789abcdef"))
}

#[actix_web::main]
async fn main() -> io::Result<()> {
    // tracing 初始化（生产建议 JSON）
    tracing_subscriber::fmt()
        .with_max_level(Level::INFO)
        .with_target(false)
        .json()
        .init();

    let state = Data::new(AppState { greeting: "hello" });

    // TLS/HTTP2（可选）：演示 rustls（自备证书）
    // let tls_config = make_rustls_config("cert.pem","key.pem")?;

    let workers = num_cpus::get().max(2); // 一般=CPU核数或略少
    info!("booting with workers={}", workers);

    HttpServer::new(move || {
        App::new()
            .app_data(state.clone())
            // 路径规范化：去尾斜杠等
            .wrap(NormalizePath::new(TrailingSlash::Trim))
            // gzip/br 压缩（大响应时更划算）
            .wrap(Compress::default())
            // 结构化日志（env: RUST_LOG=info,actix_web=info）
            .wrap(Logger::new(r#"%a %r %s %b %D "#))
            // 自定义中间件：全局 2s 超时（演示）
            .wrap(TimeoutLayer { dur: Duration::from_secs(2) })
            // 可在此插入限流/熔断/认证中间件

            .route("/healthz", web::get().to(healthz))
            .route("/hello/{name}", web::get().to(hello))
            .route("/items", web::get().to(list_items))
            .route("/bytes", web::get().to(bytes_demo))

            // 分组路由/作用域
            .service(
                web::scope("/api/v1")
                    .route("/ping", web::get().to(|| async { "pong" }))
            )
    })
    // .bind_rustls("0.0.0.0:8443", tls_config)?
    .bind(("0.0.0.0", 8080))?
    .workers(workers)
    .backlog(4096)                    // 半连接队列
    .max_connection_rate(25600)       // 每秒允许的建连速率
    .max_connections(100_000)         // 最大连接数上限（视系统 ulimit）
    .keep_alive(Duration::from_secs(60))
    .client_request_timeout(Duration::from_secs(3))
    .client_disconnect_timeout(Duration::from_secs(1))
    .run()
    .await
}

// --- 可选：rustls 配置 ---
// fn make_rustls_config(cert: &str, key: &str) -> io::Result<rustls::ServerConfig> { ... }

要点说明

• 中间件顺序：越靠近 App::new() 顶部越外层。超时/限流等建议外层，日志记录应尽量包住全链路。
• 状态数据：用 web::Data<T>（内部是 Arc<T>）。把只读热路径放里面，避免锁。
• 零拷贝：响应体优先 Bytes/Static，大文件可用 actix-files/NamedFile（sendfile）。
• HTTP/2：需要 TLS（ALPN），建议 rustls，同时注意 header 压缩与并发流控制。
• 背压：Actix 的 MessageBody 写入端在内核/用户缓冲满时会挂起 Future，天然有背压，不要把大响应一次性拼进内存。

---

4. 深入原理：Service / Transform / FromRequest

4.1 Service 洋葱模型

• Service<Request> -> Future<Response>：每个中间件和最终的 handler 都实现这个接口。
• Transform<S>：把某 Service 包装成 新 Service（高阶函数的类型版）。因此中间件是“编译期拼装的链”。

调试技巧：给中间件的 call 打 tracing，能看到请求在栈中“进/出”的耗时。

4.2 自定义提取器（FromRequest）

• 用于复杂认证、租户解析、请求签名校验等“在 handler 前完成”的逻辑。
• 要点：异步、安全失败（返回 Error），避免在 extractor 里做长阻塞。

示例：从 Header 提取租户 ID

use actix_web::{dev::Payload, Error, FromRequest, HttpRequest};
use futures_util::future::{ready, Ready};

struct Tenant(String);
impl FromRequest for Tenant {
    type Error = Error;
    type Future = Ready<Result<Self, Self::Error>>;
    fn from_request(req: &HttpRequest, _: &mut Payload) -> Self::Future {
        let v = req.headers().get("X-Tenant").and_then(|h| h.to_str().ok())
            .unwrap_or("public");
        ready(Ok(Tenant(v.to_string())))
    }
}

---

5. WebSocket / SSE（长连接场景）

WebSocket 简化示例

use actix_web::{web, HttpRequest, HttpResponse, Error};
use actix_web::web::Payload;
use actix_web_actors::ws;

struct WsEcho;
impl actix::Actor for WsEcho { type Context = ws::WebsocketContext<Self>; }
impl ws::StreamHandler<Result<ws::Message, ws::ProtocolError>> for WsEcho {
    fn handle(&mut self, msg: Result<ws::Message, ws::ProtocolError>, ctx: &mut Self::Context) {
        if let Ok(ws::Message::Text(t)) = msg { ctx.text(t); }
    }
}
async fn ws_index(req: HttpRequest, stream: Payload) -> Result<HttpResponse, Error> {
    ws::start(WsEcho, &req, stream)
}

• Actor 模型（actix crate）对长连接管理友好，每个连接一个 Actor，内部用消息传递而非共享锁。
• 注意：心跳/超时、背压、消息限速必配，防止慢客户端拖垮连接池。

---

6. 可观测性与调优

6.1 tracing 埋点

• 统一初始化：tracing_subscriber JSON 输出，字段包含 request_id、method、path、status、latency_ms、peer_ip 等。
• 中间件里用 tracing::Span 记录进入/退出时间，报错用 error! 带上 err=%e。

6.2 Prometheus 指标

• 可选 actix-web-prom / metrics + metrics-exporter-prometheus：

  • QPS、P50/P90/P99 延迟（直方图）、活动连接数、错误码计数、队列长度。

6.3 系统参数

• ulimit -n（fd 足够大）、net.core.somaxconn（大 backlog）、SO_REUSEPORT（多进程负载均衡）。
• CPU 亲和：高负载场景将 worker 绑定 NUMA、固定核（容器化请确认 CPU 配额与 runtime count）。
• TLS：rustls 避免 OpenSSL 依赖地狱；证书热更新可通过 ArcSwap 切换配置。

6.4 连接与线程

• workers = cpu_count 或 cpu_count - 1；网络 I/O 重时可等于核数。过多 worker 会导致上下文切换上升。
• max_connection_rate/max_connections/client_*_timeout 形成防御线，应有告警日志。

---

7. 测试与基准

集成测试（内存内服务器）

#[cfg(test)]
mod tests {
    use super::*;
    use actix_web::{test, http::StatusCode};

    #[actix_web::test]
    async fn test_hello() {
        let app = test::init_service(
            App::new().route("/hello/{name}", web::get().to(hello))
                .app_data(Data::new(AppState{ greeting:"hi" }))
        ).await;

        let req = test::TestRequest::get().uri("/hello/rust").to_request();
        let resp = test::call_service(&app, req).await;
        assert_eq!(resp.status(), StatusCode::OK);
        let body = test::read_body(resp).await;
        assert!(std::str::from_utf8(&body).unwrap().contains("rust"));
    }
}

压测建议

• 外部：wrk/hey/vegeta；注意设置 Connection: keep-alive 与合适的并发。
• 观察 CPU、内存、syscalls、网络栈（perf, pidstat, ss -s）。
• 常见瓶颈：日志同步写（改为异步）、响应构建分配过多、JSON 过重（可切 bincode/protobuf）、数据库连接池太小或慢查询。

---

8. 常见坑与修复

• 在异步 handler 里做阻塞 IO/CPU → 用 web::block 或单独线程池；更重的 CPU 用 Rayon。
• 中间件里偷做业务逻辑 → 让中间件只做横切关注点（认证/限流/观测），避免耦合。
• 无限制 streaming → 必须有背压/速率限制/消息大小上限。
• 全局可变状态 → 用 Data<Arc<T>> + 不可变/分片结构，或者 actor 模式封装更新。

---

9. 最小生产模板

• 功能：健康检查、JSON CRUD、零拷贝下载、分组路由、统一超时中间件、结构化日志、限制参数、优雅关停。

• 如何扩展：

  • 接入数据库：sqlx（编译期检查）或 sea-orm，连接池上限 + 慢查询日志。
  • 开启 TLS/HTTP2（rustls），用于内网 h2c 场景可考虑反代层。
  • 指标页 /metrics（Prometheus），结合 Grafana 看延迟分布。
  • 增加鉴权（actix-web-httpauth），或自定义 FromRequest 解析 JWT。

---