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