@antprofuse/saddle-skill 0.1.2 → 0.2.0-rc.19

package/references/service-0.1.1.md

@@ -1,163 +0,0 @@
-# Saddle Service 0.1.1 契约
-
-## 依赖
-
-使用已发布门面包的精确版本：
-
-```toml
-[package]
-edition = "2024"
-rust-version = "1.85"
-
-[dependencies]
-saddle-framework = "=0.1.1"
-serde = { version = "1", features = ["derive"] }
-```
-
-Cargo 包名是 `saddle-framework`，Rust 库名是 `saddle`。
-
-## 正确的最小模式
-
-定义一个零大小的契约类型、可序列化的请求/响应类型，以及独立的处理器：
-
-```rust
-use saddle::{
-    CallContext,
-    service::{Service, ServiceFuture, ServiceHandler},
-};
-use serde::{Deserialize, Serialize};
-
-struct Hello;
-
-#[derive(Deserialize)]
-struct HelloRequest {
-    name: String,
-}
-
-#[derive(Serialize)]
-struct HelloResponse {
-    message: String,
-}
-
-impl Service for Hello {
-    type Request = HelloRequest;
-    type Response = HelloResponse;
-}
-
-struct HelloHandler;
-
-impl ServiceHandler<Hello> for HelloHandler {
-    fn call<'a>(
-        &'a self,
-        _context: &'a CallContext,
-        request: HelloRequest,
-    ) -> ServiceFuture<'a, HelloResponse> {
-        Box::pin(async move {
-            Ok(HelloResponse {
-                message: format!("Hello, {}!", request.name),
-            })
-        })
-    }
-}
-```
-
-只通过 Saddle 注册并暴露 Service：
-
-```rust
-builder.register::<Hello, _>(
-    ServiceDescriptor::new("helloworld", "hello", "say_hello"),
-    HelloHandler,
-)?;
-builder.expose_json::<Hello>("/hello");
-```
-
-使用固定的进程入口：
-
-```rust
-let database_url = std::env::var("SADDLE_DATABASE_URL")
-    .expect("SADDLE_DATABASE_URL must be set by deployment configuration");
-let config = SaddleConfig::new("helloworld", database_url, listen);
-
-Saddle::run(config, |builder| {
-    // Register and expose Services here.
-    Ok(())
-})
-```
-
-完整的可编译消费端见 `examples/helloworld`。
-
-## 错误模式
-
-不要使用未固定版本或兼容版本范围：
-
-```toml
-# 错误：0.1.x 可能发生不兼容变化。
-saddle-framework = "0.1"
-```
-
-不要嵌入数据库凭据，也不要提供不安全的回退值：
-
-```rust
-// 错误：规范示例不能将密钥写入源码。
-let database_url = "mysql://user:password@127.0.0.1/application";
-
-// 错误：缺少部署配置时必须失败，不能静默使用源码中的凭据。
-let database_url = std::env::var("SADDLE_DATABASE_URL")
-    .unwrap_or_else(|_| "mysql://user:password@127.0.0.1/application".into());
-```
-
-不要从门面根模块导入 Service trait：
-
-```rust
-// 0.1.1 中错误：这些类型位于 saddle::service。
-use saddle::{Service, ServiceHandler};
-```
-
-不要使用 Tokio 或 Axum 实现业务执行入口：
-
-```rust
-// 错误：业务代码不能拥有运行时或 HTTP 服务器。
-#[tokio::main]
-async fn main() {}
-
-tokio::spawn(async move {});
-axum::Router::new();
-```
-
-不要虚构 0.1.1 未发布的便捷宏或异步 trait 语法：
-
-```rust
-// 错误：这些不是 0.1.1 中经过验证的公共 API。
-#[saddle::service]
-async fn hello(...) { ... }
-
-#[saddle::main]
-async fn main() { ... }
-```
-
-不要直接创建注册表或数据库：
-
-```rust
-// 错误：装配和托管 I/O 的创建属于 Saddle。
-let registry = saddle::service::ServiceRegistryBuilder::new();
-let database = saddle::db::Database::connect(...);
-```
-
-## 验证
-
-执行：
-
-```bash
-cargo +1.85.0 check --locked --manifest-path examples/helloworld/Cargo.toml
-cargo check --locked --manifest-path examples/helloworld/Cargo.toml
-cargo tree --locked --manifest-path examples/helloworld/Cargo.toml \
-  -p saddle-framework@0.1.1
-```
-
-当前已验证结果：
-
-- Rust 1.85 和当前工具链检查均可针对 crates.io 的 `saddle-framework 0.1.1` 制品编译。
-- 依赖树将所有 Saddle 组件解析为 0.1.1。
-- 锁文件使用 Cargo 1.85 的不兼容 Rust 版本回退机制解析，因此所有选中包都支持声明的最低 Rust 版本。
-
-该示例不能证明运行时已就绪，因为 `SADDLE_DATABASE_URL` 必须指向可访问的数据库，且配置的监听地址必须可用。