Skip to main content

yang_base/
lib.rs

1//! yang-base - YANG 基础库
2//!
3//! 提供插件管理、数据库访问、HTTP 客户端和 JWT Token 管理等核心功能。
4//!
5//! # 模块
6//!
7//! - `plugin`:插件管理模块
8//! - `database`:数据库管理模块(支持 MySQL 和 Redis)
9//! - `http`:HTTP 客户端模块(需启用 `http` feature)
10//! - `token`:JWT Token 管理模块(需启用 `token` feature)
11//! - `error`:错误处理模块
12//! - `table`:表配置系统模块
13//! - `action`:Action 系统模块
14//!
15//! # Feature Gates
16//!
17//! - `token`:启用 JWT Token 管理功能(依赖 `jsonwebtoken`)
18//! - `http`:启用 HTTP 客户端功能(依赖 `reqwest`、`serde_urlencoded`)
19//! - `mysql`:启用 MySQL 数据库查询执行功能(依赖 `sqlx`)
20//! - `redis`:启用应用实例持有的 Redis 客户端(`token` 会自动启用它)
21//! - `validator`:启用正则表达式校验器(依赖 `regex`)
22//! - `plugin-schema`:启用插件 JSON Schema 配置验证(依赖 `jsonschema`)
23//! - `admin-metadata`:启用独立后台展示描述(不新增依赖、不改变 dispatch)
24//! - `transport-axum`:启用 Axum 0.8 HTTP 传输适配器(依赖 `axum`、`tower-http`)
25//!
26//! # 快速开始
27//!
28//! ```rust,ignore
29//! use yang_base::definition::{AppBuilder, AddonSpec};
30//! use yang_base::tools::ToolsBuilder;
31//! use yang_db::{Database, DatabaseConfig};
32//!
33//! #[tokio::main]
34//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
35//!     let database = Database::connect(
36//!         "mysql://user:pass@localhost/db",
37//!         DatabaseConfig::default(),
38//!     ).await?;
39//!     let tools = ToolsBuilder::new().mysql(database).build()?;
40//!     let app = AppBuilder::new()
41//!         .addon(AddonSpec::new(yang_base::addon!("account")))
42//!         .build(tools)?;
43//!     app.tools().mysql().health_check().await?;
44//!     Ok(())
45//! }
46//! ```
47
48// 强制公开 API 文档覆盖率检查:所有公开项必须有文档注释
49#![warn(missing_docs)]
50
51/// 当前 yang-base crate 版本。
52pub const VERSION: &str = env!("CARGO_PKG_VERSION");
53
54// 让派生宏内部的 `::yang_base::...` 路径在 yang-base 自身的测试中正常解析。
55extern crate self as yang_base;
56
57pub mod action;
58#[cfg(feature = "admin-metadata")]
59pub mod admin;
60pub mod config;
61pub mod database;
62pub mod definition;
63pub mod error;
64#[cfg(feature = "http")]
65pub mod http;
66pub mod lifecycle;
67pub mod observability;
68pub mod plugin;
69pub mod router;
70pub mod table;
71#[cfg(feature = "token")]
72pub mod token;
73pub mod tools;
74pub mod transport;
75
76// 重新导出插件系统的核心类型,方便用户直接使用
77pub use plugin::{Plugin, PluginManager, PluginManagerBuilder, PluginRegistry};
78
79// 重新导出统一错误类型与 Result 别名,下游可直接写 yang_base::Result<T>
80pub use error::{BaseError, ErrorCategory, Result};
81
82// 重新导出派生宏
83pub use yang_base_derive::{params, Action};
84
85/// 直接生成原生 [`definition::Fields`];重复字段由临时结构体在编译期拒绝。
86#[macro_export]
87macro_rules! fields {
88    ($($name:ident => $builder:expr),* $(,)?) => {{
89        const _: () = {
90            $($crate::definition::__validate_field_literal(stringify!($name));)*
91        };
92        #[allow(dead_code)]
93        struct __YangFieldNames {
94            $($name: (),)*
95        }
96        let _ = __YangFieldNames { $($name: (),)* };
97        $crate::definition::Fields::new()
98            $(.field(
99                $crate::definition::FieldName::__from_validated_literal(stringify!($name)),
100                $builder,
101            ))*
102    }};
103}
104
105/// 编译期校验的 AddonName 字面量。
106#[macro_export]
107macro_rules! addon {
108    ($value:literal) => {{
109        const _: () = $crate::definition::__validate_segment_literal($value);
110        $crate::definition::AddonName::__from_validated_literal($value)
111    }};
112}
113
114/// 编译期校验的 ModuleName 字面量。
115#[macro_export]
116macro_rules! module {
117    ($value:literal) => {{
118        const _: () = $crate::definition::__validate_ref_literal($value);
119        $crate::definition::ModuleName::__from_validated_literal($value)
120    }};
121}
122
123/// 编译期校验的 TableName 字面量。
124#[macro_export]
125macro_rules! table {
126    ($value:literal) => {{
127        const _: () = $crate::definition::__validate_segment_literal($value);
128        $crate::definition::TableName::__from_validated_literal($value)
129    }};
130}
131
132/// 编译期校验的限定 FieldRef 字面量,例如 `field!("users.id")`。
133#[macro_export]
134macro_rules! field {
135    ($value:literal) => {{
136        const _: () = $crate::definition::__validate_ref_literal($value);
137        $crate::definition::FieldRef::__from_validated_literal($value)
138    }};
139}
140
141/// 编译期校验的限定 ActionRef 字面量,例如 `action!("account.user.login")`。
142#[macro_export]
143macro_rules! action {
144    ($value:literal) => {{
145        const _: () = $crate::definition::__validate_ref_literal($value);
146        $crate::definition::ActionRef::__from_validated_literal($value)
147    }};
148}
149
150/// 编译期校验的 ActionName 字面量,例如 `action_name!("login")`。
151#[macro_export]
152macro_rules! action_name {
153    ($value:literal) => {{
154        const _: () = $crate::definition::__validate_segment_literal($value);
155        $crate::definition::ActionName::__from_validated_literal($value)
156    }};
157}
158
159/// 编译期校验的限定 ViewRef 字面量。
160#[macro_export]
161macro_rules! view {
162    ($value:literal) => {{
163        const _: () = $crate::definition::__validate_ref_literal($value);
164        $crate::definition::ViewRef::__from_validated_literal($value)
165    }};
166}
167
168/// 聚合原生 Modules;每个元素直接调用 Module::into_spec。
169#[macro_export]
170macro_rules! modules {
171    ($($module:expr),* $(,)?) => {{
172        $crate::definition::Modules::new()
173            $(.module($module))*
174    }};
175}
176
177/// 原子聚合 ActionSpec 与 Handler,不支持字符串 match。
178#[macro_export]
179macro_rules! actions {
180    ($($spec:expr => $handler:expr),* $(,)?) => {{
181        $crate::definition::Actions::new()
182            $(.action($spec, $handler))*
183    }};
184    ($($handler:expr),* $(,)?) => {{
185        $crate::definition::Actions::new()
186            $(.native($handler))*
187    }};
188}