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

sz_rust_core/middleware/
request_scope.rs
