fix(contract): 补 ActionResult 的 IntoResponse;修配置变量名与雪花号回绕

- 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 <[email protected]>
This commit is contained in:
adminandClaude Code committed 2026-10-24 14:36:17 +08:00
1 parent e70de59164
commit 43fcefc6ab
3 files changed
+289 -37

No files matched your search

+106 -26
View File
@@ -28,6 +28,30 @@ impl StandaloneMode {
}
}
/// 取环境变量值;未设置或**空白**时回落默认值。
///
/// 纯函数,不读进程全局 env —— 便于单测(测试里改全局 env 会引入串行/并行竞态)。
fn env_or_default(raw: Option<String>, 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<String>, alias: Option<String>) -> 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);
}
}
+43
View File
@@ -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<Value>,
}
/// 业务信封 → HTTP 响应。
///
/// 🔴 **状态码恒为 200**,无论 `self.code` 是多少 —— 业务成败只由 body 的 `code` 表达
/// (全局约束:业务失败一律 HTTP 200 + `{code,msg,data}`)。
///
/// ⚠️ 本 impl 只服务**业务信封**。鉴权失败(401/403)是另一套形状
/// `{"success":false,"code":401,"msg":"…"}`(无 `data`),由鉴权层单独实现,
/// **不要**塞进本信封。
impl<T: Serialize> IntoResponse for ActionResult<T> {
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}));
}
}
+140 -11
View File
@@ -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<u64> {
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 不得倒退");
}
}