sz_rust_middleware_facade/
request_scope.rs

1//! 请求作用域中间件 — DI Scoped 生命周期集成
2//!
3//! P1-ARCH-DI-02 修复：将 DI 容器的 Scoped 生命周期集成到请求生命周期。
4//!
5//! ## 问题
6//!
7//! `Container::scoped()` + `make_with_scope()` + `clear_scope()` 已实现且有测试覆盖，
8//! 但整个代码库中无任何中间件调用这些方法。Scoped 生命周期在生产中等价于 Transient，
9//! 是死代码。
10//!
11//! ## 解决方案
12//!
13//! 本中间件在每个请求开始时生成唯一 `ScopeId`，通过线程本地存储（thread-local）
14//! 使请求处理链中的任意代码都能通过 `App::global().make::<T>()` 透明地获得
15//! Scoped 语义；请求结束时自动调用 `clear_scope` 释放作用域内所有缓存实例。
16//!
17//! ## 使用
18//!
19//! ```rust,ignore
20//! use sz_rust_core::middleware::request_scope::RequestScopeLayer;
21//! use tower::ServiceBuilder;
22//!
23//! let service = ServiceBuilder::new()
24//!     .layer(RequestScopeLayer::new())
25//!     .service(inner);
26//! ```
27//!
28//! 业务代码无需任何改动：
29//!
30//! ```rust,ignore
31//! // 注册 Scoped 服务（通常在 App::init 中）
32//! App::with(|app| {
33//!     app.scoped(|| RequestCache::new());
34//! });
35//!
36//! // 请求处理中 — 同一请求内多次 make 返回同一实例
37//! let cache = App::global().unwrap().make::<RequestCache>();
38//! ```
39
40use axum::http::{Request, Response};
41use std::cell::RefCell;
42use std::future::Future;
43use std::pin::Pin;
44use std::sync::atomic::{AtomicU64, Ordering};
45use std::task::{Context, Poll};
46use tower::Service;
47
48use crate::ScopeId;
49
50// 当前请求的作用域 ID（线程本地存储）
51// 由 [`RequestScopeLayer`] 在请求开始时设置，请求结束时清除。
52// 值为 `0` 表示当前不在请求作用域内（默认值）。
53thread_local! {
54    static CURRENT_SCOPE_ID: RefCell<ScopeId> = const { RefCell::new(0) };
55}
56
57/// 获取当前线程的请求作用域 ID
58///
59/// 返回 `Some(id)` 当且仅当当前线程正处于 [`RequestScopeLayer`] 管理的请求中；
60/// 否则返回 `None`（即 `CURRENT_SCOPE_ID` 为 `0`）。
61///
62/// DI 容器内部通过此函数决定是否为 Scoped 绑定缓存实例。
63pub fn current_scope_id() -> Option<ScopeId> {
64    CURRENT_SCOPE_ID.with(|c| {
65        let id = *c.borrow();
66        if id != 0 {
67            Some(id)
68        } else {
69            None
70        }
71    })
72}
73
74/// 全局作用域 ID 生成器（单调递增，保证唯一性）
75static SCOPE_ID_COUNTER: AtomicU64 = AtomicU64::new(1);
76
77/// 生成唯一的请求作用域 ID
78fn generate_scope_id() -> ScopeId {
79    SCOPE_ID_COUNTER.fetch_add(1, Ordering::Relaxed)
80}
81
82// ============================================================================
83// RequestScopeLayer
84// ============================================================================
85
86/// 请求作用域 Layer（对齐 PHP 请求生命周期中的 `app()->scoped()` 语义）
87///
88/// 每个请求分配唯一 `ScopeId`，请求结束时清理。
89#[derive(Clone, Default)]
90pub struct RequestScopeLayer;
91
92impl RequestScopeLayer {
93    /// 创建新的请求作用域 Layer
94    pub fn new() -> Self {
95        Self
96    }
97}
98
99impl<S> tower::Layer<S> for RequestScopeLayer {
100    type Service = RequestScopeService<S>;
101
102    fn layer(&self, inner: S) -> Self::Service {
103        RequestScopeService { inner }
104    }
105}
106
107// ============================================================================
108// RequestScopeService
109// ============================================================================
110
111/// 请求作用域 Service（由 [`RequestScopeLayer`] 创建）
112#[derive(Clone)]
113pub struct RequestScopeService<S> {
114    inner: S,
115}
116
117impl<S, ReqBody, ResBody> Service<Request<ReqBody>> for RequestScopeService<S>
118where
119    S: Service<Request<ReqBody>, Response = Response<ResBody>> + Clone + Send + 'static,
120    S::Future: Send + 'static,
121    ReqBody: Send + 'static,
122    ResBody: axum::body::HttpBody + Send + 'static,
123    ResBody::Data: Send,
124    ResBody::Error: Into<Box<dyn std::error::Error + Send + Sync>>,
125{
126    type Response = Response<ResBody>;
127    type Error = S::Error;
128    type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>> + Send>>;
129
130    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
131        self.inner.poll_ready(cx)
132    }
133
134    fn call(&mut self, req: Request<ReqBody>) -> Self::Future {
135        // 为当前请求生成唯一作用域 ID
136        let scope_id = generate_scope_id();
137
138        // 设置线程本地作用域 ID
139        CURRENT_SCOPE_ID.with(|c| *c.borrow_mut() = scope_id);
140
141        // 调用内部服务（clone 遵循 tower Service 协议：call 时 inner 已就绪）
142        let future = self.inner.clone().call(req);
143
144        Box::pin(async move {
145            let response = future.await?;
146            // 请求处理完毕，清除作用域
147            CURRENT_SCOPE_ID.with(|c| *c.borrow_mut() = 0);
148            Ok(response)
149        })
150    }
151}
152
153// ============================================================================
154// 单元测试
155// ============================================================================
156
157#[cfg(test)]
158mod tests {
159    use super::*;
160    use axum::body::Body;
161    use axum::http::{Method, Request, StatusCode};
162    use tower::Layer;
163
164    /// 简单的 Echo Service，用于测试
165    #[derive(Clone)]
166    struct EchoService;
167
168    impl Service<Request<Body>> for EchoService {
169        type Response = Response<Body>;
170        type Error = std::convert::Infallible;
171        type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>> + Send>>;
172
173        fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
174            Poll::Ready(Ok(()))
175        }
176
177        fn call(&mut self, _req: Request<Body>) -> Self::Future {
178            Box::pin(async {
179                Ok(Response::builder()
180                    .status(StatusCode::OK)
181                    .body(Body::from("ok"))
182                    .unwrap())
183            })
184        }
185    }
186
187    #[tokio::test]
188    async fn test_p1_arch_di_02_scope_layer_sets_and_clears_scope() {
189        // 请求外应为 None
190        assert!(
191            current_scope_id().is_none(),
192            "请求外 current_scope_id 应为 None"
193        );
194
195        let layer = RequestScopeLayer::new();
196        let mut service = layer.layer(EchoService);
197
198        let req = Request::builder()
199            .method(Method::GET)
200            .uri("/")
201            .body(Body::empty())
202            .unwrap();
203        let resp = service.call(req).await.unwrap();
204        assert_eq!(resp.status(), StatusCode::OK);
205
206        // 请求结束后应恢复为 None
207        assert!(
208            current_scope_id().is_none(),
209            "请求结束后 current_scope_id 应恢复为 None"
210        );
211    }
212
213    #[tokio::test]
214    async fn test_p1_arch_di_02_scope_id_unique_per_request() {
215        let mut seen_ids = Vec::new();
216        for _ in 0..5 {
217            // 直接验证每次生成的 scope_id 不同
218            let id1 = generate_scope_id();
219            let id2 = generate_scope_id();
220            assert_ne!(id1, id2, "连续生成的 scope_id 应不同");
221            seen_ids.push(id1);
222        }
223
224        // 验证所有 ID 唯一
225        for (i, &id1) in seen_ids.iter().enumerate() {
226            for &id2 in seen_ids.iter().skip(i + 1) {
227                assert_ne!(id1, id2, "scope_id 应全局唯一");
228            }
229        }
230    }
231
232    /// 验证 RequestScopeService 实现 Send
233    fn assert_send<T: Send>() {}
234
235    #[test]
236    fn test_p1_arch_di_02_service_is_send() {
237        assert_send::<RequestScopeService<EchoService>>();
238    }
239}
sz_rust_middleware_facade/request_scope.rs

sz_rust_middleware_facade/
request_scope.rs
