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:
1 parent
e70de59164
commit
43fcefc6ab
3 files changed
+289
-37
No files matched your search
+106
-26
@@ -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);
|
||||
}
|
||||
}
|
||||
@@ -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
@@ -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 不得倒退");
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user