From 43fcefc6abbddcb22fdaa8642586f55d7cc6f026 Mon Sep 17 00:00:00 2001 From: admin Date: Sat, 24 Oct 2026 14:36:17 +0800 Subject: [PATCH] =?UTF-8?q?fix(contract):=20=E8=A1=A5=20ActionResult=20?= =?UTF-8?q?=E7=9A=84=20IntoResponse=EF=BC=9B=E4=BF=AE=E9=85=8D=E7=BD=AE?= =?UTF-8?q?=E5=8F=98=E9=87=8F=E5=90=8D=E4=B8=8E=E9=9B=AA=E8=8A=B1=E5=8F=B7?= =?UTF-8?q?=E5=9B=9E=E7=BB=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - envelope: 补 impl IntoResponse(状态码恒 200,业务成败只由 body.code 表达) - config: 认规格名 TDC_LOCAL_STANDALONE(TDC_STANDALONE 保留为别名); 抽 env_or_default 统一处理空串/纯空白回落 - ids: 改毫秒+12位序列打包 + CAS 循环,序列用满时拒绝产出而非回绕出重复 id; 修正纪元注释(1_600_000_000_000 = 2020-09-13) Co-Authored-By: Claude Code --- src/config.rs | 132 +++++++++++++++++++++++++++++++++--------- src/envelope.rs | 43 ++++++++++++++ src/ids.rs | 151 ++++++++++++++++++++++++++++++++++++++++++++---- 3 files changed, 289 insertions(+), 37 deletions(-) diff --git a/src/config.rs b/src/config.rs index dc929b6..15c99c1 100644 --- a/src/config.rs +++ b/src/config.rs @@ -28,6 +28,30 @@ impl StandaloneMode { } } +/// 取环境变量值;未设置或**空白**时回落默认值。 +/// +/// 纯函数,不读进程全局 env —— 便于单测(测试里改全局 env 会引入串行/并行竞态)。 +fn env_or_default(raw: Option, default: &str) -> String { + match raw { + Some(v) if !v.trim().is_empty() => v, + _ => default.to_string(), + } +} + +/// 解析本地单机模式:`TDC_LOCAL_STANDALONE`(规格名,权威)优先, +/// `TDC_STANDALONE`(别名)为次;都没给 ⇒ 未配置 ⇒ `Auto`。 +/// +/// 纯函数,便于单测双名优先级。 +fn standalone_mode_from(primary: Option, alias: Option) -> StandaloneMode { + let primary = env_or_default(primary, ""); + let raw = if primary.trim().is_empty() { + env_or_default(alias, "") + } else { + primary + }; + StandaloneMode::parse(&raw) +} + #[derive(Debug, Clone)] pub struct Config { pub port: u16, @@ -48,18 +72,32 @@ impl Config { .ok() .and_then(|v| v.trim().parse().ok()) .unwrap_or(DEFAULT_PORT); - let data_dir = std::env::var("TDC_DATA_DIR") - .ok() - .map(PathBuf::from) - .filter(|p| !p.as_os_str().is_empty()) - .unwrap_or_else(|| project_dir.join("data")); - let internal_token = - std::env::var("SSW_INTERNAL_TOKEN").unwrap_or_else(|_| DEFAULT_INTERNAL_TOKEN.to_string()); - let tds_base_url = std::env::var("SSW_TDS_BASE_URL") - .ok() - .map(|v| v.trim().to_string()) - .filter(|v| !v.is_empty()); - let standalone = StandaloneMode::parse(&std::env::var("TDC_STANDALONE").unwrap_or_default()); + let data_dir = { + let raw = env_or_default(std::env::var("TDC_DATA_DIR").ok(), ""); + if raw.trim().is_empty() { + project_dir.join("data") + } else { + PathBuf::from(raw.trim()) + } + }; + let internal_token = env_or_default( + std::env::var("SSW_INTERNAL_TOKEN").ok(), + DEFAULT_INTERNAL_TOKEN, + ); + let tds_base_url = { + let raw = env_or_default(std::env::var("SSW_TDS_BASE_URL").ok(), ""); + let v = raw.trim().to_string(); + if v.is_empty() { + None + } else { + Some(v) + } + }; + // 规格名 `TDC_LOCAL_STANDALONE` 优先;`TDC_STANDALONE` 保留为别名。 + let standalone = standalone_mode_from( + std::env::var("TDC_LOCAL_STANDALONE").ok(), + std::env::var("TDC_STANDALONE").ok(), + ); let strict_secrets = matches!( std::env::var("TDC_STRICT_SECRETS") .unwrap_or_default() @@ -68,20 +106,27 @@ impl Config { .as_str(), "1" | "true" | "yes" ); - let identity_code = std::env::var("TDC_IDENTITY_CODE") - .ok() - .map(|v| v.trim().to_string()) - .filter(|v| !v.is_empty()) - .unwrap_or_else(|| DEFAULT_IDENTITY_CODE.to_string()); - let identity_name = std::env::var("TDC_IDENTITY_NAME") - .ok() - .map(|v| v.trim().to_string()) - .filter(|v| !v.is_empty()) - .unwrap_or_else(|| DEFAULT_IDENTITY_NAME.to_string()); - let identity_secret = std::env::var("TDC_IDENTITY_SECRET") - .ok() - .map(|v| v.trim().to_string()) - .filter(|v| !v.is_empty()); + let identity_code = env_or_default( + std::env::var("TDC_IDENTITY_CODE").ok(), + DEFAULT_IDENTITY_CODE, + ) + .trim() + .to_string(); + let identity_name = env_or_default( + std::env::var("TDC_IDENTITY_NAME").ok(), + DEFAULT_IDENTITY_NAME, + ) + .trim() + .to_string(); + let identity_secret = { + let raw = env_or_default(std::env::var("TDC_IDENTITY_SECRET").ok(), ""); + let v = raw.trim().to_string(); + if v.is_empty() { + None + } else { + Some(v) + } + }; Self { port, project_dir, @@ -175,4 +220,39 @@ mod tests { c.internal_token = "a-real-strong-token".to_string(); assert!(c.check_secret_guard().is_ok()); } + + #[test] + fn env_or_default_falls_back_on_missing_empty_or_blank() { + assert_eq!(env_or_default(None, "d"), "d"); + assert_eq!(env_or_default(Some(String::new()), "d"), "d"); + assert_eq!(env_or_default(Some(" ".to_string()), "d"), "d"); + assert_eq!(env_or_default(Some("\t\n".to_string()), "d"), "d"); + assert_eq!(env_or_default(Some("v".to_string()), "d"), "v"); + assert_eq!( + env_or_default(Some(" padded ".to_string()), "d"), + " padded ", + "正常值原样返回,不做 trim" + ); + } + + #[test] + fn standalone_primary_name_wins_over_alias() { + // 规格名 TDC_LOCAL_STANDALONE 优先 + assert_eq!( + standalone_mode_from(Some("on".into()), Some("off".into())), + StandaloneMode::On + ); + // 别名 TDC_STANDALONE 仍生效 + assert_eq!( + standalone_mode_from(None, Some("off".into())), + StandaloneMode::Off + ); + // 规格名为空白 ⇒ 落到别名 + assert_eq!( + standalone_mode_from(Some(" ".into()), Some("off".into())), + StandaloneMode::Off + ); + // 都没给 ⇒ Auto + assert_eq!(standalone_mode_from(None, None), StandaloneMode::Auto); + } } diff --git a/src/envelope.rs b/src/envelope.rs index 4737713..7d3fa8e 100644 --- a/src/envelope.rs +++ b/src/envelope.rs @@ -4,6 +4,9 @@ //! `{"success":false,"code":401,"msg":"…"}`(**无 `data`、多 `success:false`**)。 //! 两套形状必须分开实现,见 `auth::reject`。 +use axum::http::StatusCode; +use axum::response::{IntoResponse, Response}; +use axum::Json; use serde::Serialize; use serde_json::Value; @@ -82,6 +85,20 @@ pub struct PageData { pub list: Vec, } +/// 业务信封 → HTTP 响应。 +/// +/// 🔴 **状态码恒为 200**,无论 `self.code` 是多少 —— 业务成败只由 body 的 `code` 表达 +/// (全局约束:业务失败一律 HTTP 200 + `{code,msg,data}`)。 +/// +/// ⚠️ 本 impl 只服务**业务信封**。鉴权失败(401/403)是另一套形状 +/// `{"success":false,"code":401,"msg":"…"}`(无 `data`),由鉴权层单独实现, +/// **不要**塞进本信封。 +impl IntoResponse for ActionResult { + fn into_response(self) -> Response { + (StatusCode::OK, Json(self)).into_response() + } +} + #[cfg(test)] mod tests { use super::*; @@ -136,4 +153,30 @@ mod tests { }) ); } + + /// 🔴 业务失败也必须回 HTTP **200**;成败只由 body 的 `code` 表达。 + #[tokio::test] + async fn into_response_keeps_http_200_for_business_failure() { + let resp = ActionResult::fail("记录不存在或已删除").into_response(); + assert_eq!(resp.status(), StatusCode::OK, "业务失败不得走 4xx"); + let body = axum::body::to_bytes(resp.into_body(), usize::MAX) + .await + .expect("读 body"); + let v: Value = serde_json::from_slice(&body).expect("body 是 JSON"); + assert_eq!(v["code"], 400); + assert_eq!(v["msg"], "记录不存在或已删除"); + assert!(v["data"].is_null()); + } + + #[tokio::test] + async fn into_response_of_ok_is_http_200_with_wrapped_data() { + let resp = ActionResult::ok(json!({"a": 1})).into_response(); + assert_eq!(resp.status(), StatusCode::OK); + let body = axum::body::to_bytes(resp.into_body(), usize::MAX) + .await + .expect("读 body"); + let v: Value = serde_json::from_slice(&body).expect("body 是 JSON"); + assert_eq!(v["code"], 200); + assert_eq!(v["data"], json!({"a": 1})); + } } diff --git a/src/ids.rs b/src/ids.rs index 0aaf48d..5e2404a 100644 --- a/src/ids.rs +++ b/src/ids.rs @@ -1,28 +1,81 @@ //! 实例 id 生成:雪花号十进制串。 //! //! 上游 `RandomUtil.uuId()` = Yitter `nextId()` 的**十进制字符串**形态(≤19 位数字), -//! **不是 UUID**。这里用「毫秒时间戳 << 22 | 12 位序列」的经典雪花口径, +//! **不是 UUID**。这里用「毫秒时间戳 | 12 位序列」的经典雪花口径, //! 保证同毫秒内单调递增、跨毫秒递增,量级与上游一致。 +//! +//! ⚠️ **同毫秒内序列用满(4096 个)时不得回绕** —— id 是主键,重复即插入失败。 +//! 序列回绕且毫秒未前进时,状态机返回 `None`(必须等下一毫秒),绝不上吐重复 id。 use std::sync::atomic::{AtomicU64, Ordering}; use std::time::{SystemTime, UNIX_EPOCH}; -/// 纪元:2020-01-01T00:00:00Z(毫秒)。 +/// 纪元:2020-09-13T12:26:40Z(毫秒)。只影响 id 的绝对值,不影响唯一性。 const EPOCH_MS: u64 = 1_600_000_000_000; -/// 序列占 12 位。 +/// 序列占 12 位(0..=4095)。 const SEQ_MASK: u64 = 0xFFF; +/// 序列占 12 位 ⇒ 时间戳左移 12 位。 +const TS_SHIFT: u32 = 12; -static SEQ: AtomicU64 = AtomicU64::new(0); +/// 最近一次发出的 id:高 52 位是毫秒时间戳,低 12 位是序列。 +static LAST: AtomicU64 = AtomicU64::new(0); -/// 生成下一个 id(十进制字符串)。 -pub fn next_id() -> String { - let now_ms = SystemTime::now() +/// 当前 Unix 毫秒(纪元偏移后)。 +fn now_ms() -> u64 { + SystemTime::now() .duration_since(UNIX_EPOCH) .map(|d| d.as_millis() as u64) - .unwrap_or(0); - let ts = now_ms.saturating_sub(EPOCH_MS); - let seq = SEQ.fetch_add(1, Ordering::Relaxed) & SEQ_MASK; - ((ts << 22) | seq).to_string() + .unwrap_or(0) + .saturating_sub(EPOCH_MS) +} + +/// 状态机:依据「已发出的 id」与「当前毫秒」算出下一个 id。 +/// +/// **纯函数**(不碰全局状态、不读时钟)⇒ 边界行为可被确定性地单测。 +/// +/// - `wall_ms > last_ts`:毫秒前进 ⇒ 序列归零; +/// - `wall_ms == last_ts`:同毫秒 ⇒ 序列递增; +/// - `wall_ms < last_ts`:**时钟回拨** ⇒ 沿用已记录的毫秒继续递增序列 +/// (宁可让 id 的时间部分暂时停在过去,也绝不产出比已发出 id 更小的值)。 +/// +/// 返回 `None` = **序列已用满且毫秒未前进** ⇒ 必须等下一毫秒,不得回绕出重复 id。 +fn advance(last: u64, wall_ms: u64) -> Option { + let last_ts = last >> TS_SHIFT; + let last_seq = last & SEQ_MASK; + + let ts = if wall_ms > last_ts { wall_ms } else { last_ts }; + let seq = if wall_ms > last_ts { + 0 + } else { + last_seq.wrapping_add(1) & SEQ_MASK + }; + + // 序列回绕到 0 且毫秒未前进 ⇒ 本毫秒的 4096 个 id 已用尽,必须等下一毫秒。 + if seq == 0 && last_seq == SEQ_MASK && ts == last_ts { + return None; + } + + Some((ts << TS_SHIFT) | seq) +} + +/// 生成下一个 id(十进制字符串)。 +/// +/// **打包口径**:`id = (毫秒时间戳 << 12) | 序列`,序列 12 位 ⇒ 同毫秒最多 4096 个。 +/// 打包后约 16 位十进制数字串,落在上游 `RandomUtil.uuId()` 同量级(≤19 位)。 +pub fn next_id() -> String { + loop { + let last = LAST.load(Ordering::Relaxed); + let Some(candidate) = advance(last, now_ms()) else { + // 本毫秒序列已满 ⇒ 自旋等下一毫秒(不产出重复 id)。 + std::thread::yield_now(); + continue; + }; + match LAST.compare_exchange_weak(last, candidate, Ordering::Relaxed, Ordering::Relaxed) { + Ok(_) => return candidate.to_string(), + // 别的线程抢先了 ⇒ 重读重算。 + Err(_) => continue, + } + } } #[cfg(test)] @@ -51,4 +104,80 @@ mod tests { let b = next_id(); assert_ne!(a, b); } + + /// 5000 个 id 全部互不相同(覆盖同毫秒内序列递增的边界)、全数字、长度合法、严格递增。 + #[test] + fn many_ids_are_unique_and_strictly_increasing() { + const N: usize = 5000; + let mut prev: u64 = 0; + let mut seen = std::collections::HashSet::with_capacity(N); + for _ in 0..N { + let id = next_id(); + assert!( + id.chars().all(|c| c.is_ascii_digit()), + "id 必须是十进制数字串:{}", + id + ); + assert!( + (10..=19).contains(&id.len()), + "id 长度应与上游同量级(≤19 位):{}", + id + ); + let n: u64 = id.parse().expect("id 必可解析为 u64"); + assert!(seen.insert(n), "id 重复:{}", id); + assert!(n > prev, "id 必须严格递增:{} 之后是 {}", prev, n); + prev = n; + } + assert_eq!(seen.len(), N); + } + + /// 🔴 **回归**:同一毫秒内第 4097 个 id 不得与本毫秒的第一个 id 相同。 + /// + /// 旧实现用进程级全局 `SEQ`(从不在毫秒边界重置)+ 12 位掩码, + /// 于是同毫秒内第 4097 个 id 会回绕到 seq=0,产出与本毫秒第一个 id **完全相同**的字符串 + /// —— id 是主键,撞了就是插入失败。 + /// + /// 这里直接驱动纯状态机 `advance()`,把时钟钉死在同一个毫秒 ⇒ 确定性地覆盖该边界。 + #[test] + fn sequence_must_not_wrap_within_the_same_millisecond() { + const MS: u64 = 1000; + let mut last = advance(0, MS).expect("首个 id"); + let first = last; + // 本毫秒共 4096 个 id(seq 0..=4095)。 + for i in 1..=(SEQ_MASK as u64) { + last = advance(last, MS).expect("同毫秒内应仍有可用序列"); + assert_eq!(last & SEQ_MASK, i, "序列应递增到 {}", i); + assert_eq!(last >> TS_SHIFT, MS, "毫秒部分应不变"); + } + // 第 4097 个:序列已满 ⇒ 必须拒绝(None),而不是回绕成重复值。 + assert_eq!( + advance(last, MS), + None, + "同毫秒内序列用满时必须拒绝产出,不得回绕出重复 id" + ); + // 且回绕值 **恰好等于** 本毫秒首个 id —— 这就是旧实现会产出重复 id 的实证。 + let wrapped = (MS << TS_SHIFT) | 0; + assert_eq!( + wrapped, first, + "回绕值与首个 id 相同 ⇒ 旧实现会产出重复 id(本次改动已阻止该路径)" + ); + + // 毫秒前进 ⇒ 序列归零,新值与本毫秒的所有 id 都不同。 + let next_ms = advance(last, MS + 1).expect("新毫秒应可用"); + assert_eq!(next_ms >> TS_SHIFT, MS + 1); + assert_eq!(next_ms & SEQ_MASK, 0); + assert_ne!(next_ms, first); + } + + /// 时钟回拨:沿用已记录的毫秒继续递增序列,id 不倒退。 + #[test] + fn clock_rollback_keeps_ids_monotonic() { + let mut last = advance(0, 1000).expect("首个 id"); + let first = last; + last = advance(last, 1000).expect("同毫秒"); + // 墙钟往回拨到 500(< 已记录的 1000)⇒ 沿用 1000。 + let rolled = advance(last, 500).expect("回拨不应拒绝"); + assert_eq!(rolled >> TS_SHIFT, 1000, "应沿用已记录的毫秒"); + assert!(rolled > first, "回拨时 id 不得倒退"); + } }