Struct TushareClient 

pub struct TushareClient { /* private fields */ }

Tushare API client

Implementations

impl TushareClient

pub fn builder() -> TushareClientBuilder

Create client builder

Examples found in repository

examples/tracing_example.rs (line 47)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== Tushare API Tracing Integration Example ===");
    
    // Method 1: Using tracing-log bridge (recommended for mixed ecosystems)
    #[cfg(all(feature = "tracing", feature = "tracing-log"))] 
    {
        println!("\n--- Method 1: Using tracing-log bridge ---");
        use tracing_subscriber;
        use tracing_log::LogTracer;
        
        // Initialize log-to-tracing bridge
        LogTracer::init()?;
        
        // Set up tracing subscriber
        tracing_subscriber::fmt()
            .with_env_filter("debug")
            .with_target(false)
            .with_thread_ids(true)
            .with_level(true)
            .with_max_level(tracing::Level::DEBUG)
            .init();
    }
    
    // Method 2: Using native tracing feature (when library is compiled with tracing feature)
    #[cfg(feature = "tracing")]
    {
        println!("\n--- Method 2: Using native tracing feature ---");
        println!("库和用户程序都使用 tracing\n");
        
        // 直接初始化 tracing subscriber
        tracing_subscriber::fmt()
            .with_max_level(tracing::Level::DEBUG)
            .init();
    }

    println!("初始化 Tushare 客户端...");
    
    let client = TushareClient::builder()
        .with_token("demo_token_for_testing")
        .with_log_level(LogLevel::Debug)
        .log_requests(true)
        .log_responses(false)
        .log_performance(true)
        .build()?;

    println!("创建测试请求...");
    
    let mut params = HashMap::new();
    params.insert("list_status".to_string(), "L".to_string());
    
    let request = TushareRequest {
        api_name: Api::StockBasic,
        params,
        fields: vec!["ts_code".to_string(), "name".to_string()],
    };

    println!("发送 API 请求（注意观察日志输出）...");
    
    // 这会触发我们库的日志输出
    match client.call_api(&request).await {
        Ok(_response) => {
            println!("✅ API 调用成功（实际会因为 token 无效而失败，但能看到日志）");
        }
        Err(e) => {
            println!("❌ API 调用失败（预期行为）: {}", e);
        }
    }

    #[cfg(not(feature = "tracing"))]
    {
        println!("\n--- Tracing feature not enabled ---");
        println!("To enable tracing support, compile with: cargo build --features tracing");
        println!("Or add tracing-log bridge support with: cargo build --features tracing-log");
    }

    println!("\n=== 总结 ===");
    #[cfg(feature = "tracing")]
    println!("✅ 使用了原生 tracing 支持，日志输出更加结构化");
    
    #[cfg(not(feature = "tracing"))]
    println!("✅ 使用了 tracing-log 桥接，成功捕获了库的 log 输出");

    Ok(())
}

examples/logging_example.rs (line 14)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 注意：在实际使用中，您需要初始化一个日志记录器（如 env_logger）
    // env_logger::init();

    println!("=== Tushare API 日志功能演示 ===\n");

    // 示例 1: 使用默认日志配置
    println!("1. 使用默认日志配置:");
    let client1 = TushareClient::builder()
        .with_token("your_token_here")
        .build()?;

    // 示例 2: 自定义日志级别
    println!("\n2. 自定义日志级别为 Debug:");
    let client2 = TushareClient::builder()
        .with_token("your_token_here")
        .with_log_level(LogLevel::Debug)
        .build()?;

    // 示例 3: 详细的日志配置
    println!("\n3. 详细的日志配置:");
    let client3 = TushareClient::builder()
        .with_token("your_token_here")
        .with_log_level(LogLevel::Trace)
        .log_requests(true)
        .log_responses(true)
        .log_sensitive_data(false) // 生产环境建议设为 false
        .log_performance(true)
        .with_connect_timeout(Duration::from_secs(5))
        .with_timeout(Duration::from_secs(30))
        .build()?;

    // 示例 4: 使用自定义 LogConfig
    println!("\n4. 使用自定义 LogConfig:");
    let log_config = LogConfig {
        level: LogLevel::Info,
        log_requests: true,
        log_responses: false,
        log_responses_err: true,
        log_sensitive_data: false,
        log_performance: true,
    };
    
    let client4 = TushareClient::builder()
        .with_token("your_token_here")
        .with_log_config(log_config)
        .build()?;

    // 示例 5: 关闭日志
    println!("\n5. 关闭日志:");
    let client5 = TushareClient::builder()
        .with_token("your_token_here")
        .with_log_level(LogLevel::Off)
        .build()?;

    // 演示 API 调用（需要有效的 token）
    if std::env::var("TUSHARE_TOKEN").is_ok() {
        println!("\n=== 实际 API 调用演示 ===");
        
        let client = TushareClient::builder()
            .with_token(&std::env::var("TUSHARE_TOKEN")?)
            .with_log_level(LogLevel::Info)
            .log_performance(true)
            .build()?;

        let mut params = HashMap::new();
        params.insert("list_status".to_string(), "L".to_string());
        
        let req = TushareRequest {
            api_name: Api::StockBasic,
            params,
            fields: vec!["ts_code".to_string(), "name".to_string()],
        };

        match client.call_api(&req).await {
            Ok(response) => {
                if let Some(data) = response.data {
                    println!("✅ API 调用成功，返回 {} 条记录", data.items.len());
                }
            }
            Err(e) => {
                println!("❌ API 调用失败: {}", e);
            }
        }
    } else {
        println!("\n💡 提示: 设置 TUSHARE_TOKEN 环境变量以查看实际的 API 调用日志");
    }

    println!("\n=== 日志级别说明 ===");
    println!("• Off    - 关闭所有日志");
    println!("• Error  - 只记录错误信息");
    println!("• Warn   - 记录错误和警告");
    println!("• Info   - 记录基本信息（推荐）");
    println!("• Debug  - 记录详细调试信息");
    println!("• Trace  - 记录所有信息包括原始数据");

    println!("\n=== 日志配置选项说明 ===");
    println!("• log_requests      - 是否记录请求参数");
    println!("• log_responses     - 是否记录响应内容（可能很大）");
    println!("• log_sensitive_data - 是否记录敏感数据（如 token）");
    println!("• log_performance   - 是否记录性能指标（耗时等）");

    Ok(())
}

pub fn new(token: &str) -> Self

Create a new Tushare client with default timeout settings

Arguments

• token - Tushare API Token

Example

use tushare_api::TushareClient;
 
let client = TushareClient::new("your_token_here");

Examples found in repository

examples/generic_api_usage.rs (line 11)

async fn main() -> TushareResult<()> {
    // 从环境变量获取 Tushare token
    let token = env::var("TUSHARE_TOKEN")
        .expect("请设置环境变量 TUSHARE_TOKEN");

    // 创建客户端
    let client = TushareClient::new(&token);

    println!("=== 使用通用 API 方法获取股票列表 ===");
    
    // 使用宏构建请求（支持直接使用字符串字面量）
    let request = TushareRequest {
        api_name: Api::StockBasic,
        params: params!("list_status" => "L"),
        fields: fields!["ts_code", "symbol", "name", "area", "industry", "list_date"],
    };
    
    // 调用通用 API 方法
    let response = client.call_api(&request).await?;
    
    println!("API 调用成功！");
    println!("请求 ID: {}", response.request_id);
    println!("返回码: {}", response.code);
    if let Some(data) = response.data {
        println!("返回字段: {:?}", data.fields);
        println!("数据条数: {}", data.items.len());
        
        // 显示前5条记录
        println!("\n前5条股票记录:");
        for (i, item) in data.items.iter().take(5).enumerate() {
            println!("{}. {:?}", i + 1, item);
        }
    }
    
    println!("\n=== 使用通用 API 方法查询特定股票 ===");
    
    // 查询特定股票
    let request = TushareRequest {
        api_name: Api::StockBasic,
        params: params!("ts_code" => "000001.SZ"),
        fields: fields!["ts_code", "name", "industry", "market", "list_date"],
    };
    
    let response = client.call_api(&request).await?;

    if let Some(data) = response.data {
        if let Some(stock_data) = data.items.first() {
            println!("找到股票信息:");
            for (field, value) in data.fields.iter().zip(stock_data.iter()) {
                println!("  {}: {}", field, value);
            }
        } else {
            println!("未找到该股票");
        }
    }

    Ok(())
}

examples/basic_usage.rs (line 13)

async fn main() -> TushareResult<()> {
    // 从环境变量获取 token
    let token = env::var("TUSHARE_TOKEN")
        .expect("请设置环境变量 TUSHARE_TOKEN");

    // 创建客户端（使用默认超时设置）
    let client = TushareClient::new(&token);
    
    println!("=== 使用默认超时设置获取股票基本信息 ===");
    
    let request = TushareRequest {
        api_name: Api::StockBasic,
        params: params!("list_status" => "L"),
        fields: fields!["ts_code", "name", "industry", "area"],
    };
    
    match client.call_api(&request).await {
        Ok(response) => {
            if let Some(data) = response.data {
                println!("成功获取到 {} 条记录", data.items.len());

                // 显示前10条记录
                println!("\n前10条股票信息:");
                for (i, item) in data.items.iter().take(10).enumerate() {
                    println!("{}. {:?}", i + 1, item);
                }
            }
        }
        Err(e) => {
            eprintln!("获取股票列表失败: {}", e);
        }
    }
    
    println!("\n=== 使用自定义超时设置查询特定股票 ===");
    
    // 创建客户端（自定义超时设置）
    let client_with_timeout = TushareClient::with_timeout(
        &token,
        Duration::from_secs(5),  // 连接超时 5 秒
        Duration::from_secs(60)  // 请求超时 60 秒
    );
    
    let mut stock_params = HashMap::new();
    stock_params.insert("ts_code".into(), "000001.SZ".into());
    
    let stock_request = TushareRequest {
        api_name: Api::StockBasic,
        params: stock_params,
        fields: vec![
            "ts_code".into(),
            "symbol".into(),
            "name".into(),
            "area".into(),
            "industry".into(),
            "list_date".into(),
        ],
    };
    
    match client_with_timeout.call_api(&stock_request).await {
        Ok(response) => {
            if let Some(data) = response.data {
                if let Some(item) = data.items.first() {
                    println!("找到股票信息:");
                    for (field, value) in data.fields.iter().zip(item.iter()) {
                        println!("  {}: {}", field, value);
                    }
                } else {
                    println!("未找到该股票");
                }
            }
        }
        Err(e) => {
            eprintln!("查询股票失败: {}", e);
        }
    }

    Ok(())
}

pub fn from_env() -> TushareResult<Self>

Create a new Tushare client from TUSHARE_TOKEN environment variable with default timeout settings

Errors

Returns TushareError::InvalidToken if TUSHARE_TOKEN environment variable does not exist or is empty

Example

use tushare_api::{TushareClient, TushareResult};
 
// Requires TUSHARE_TOKEN environment variable to be set
let client = TushareClient::from_env()?;

Examples found in repository

examples/stock_conversion_example.rs (line 14)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client (you need to set TUSHARE_TOKEN environment variable)
    let client = TushareClient::from_env()?;

    // Create request for stock basic data
    let request = request!(Api::StockBasic, {
        "list_status" => "L"
    }, [
        "ts_code", "symbol", "name"
    ]);

    // Use the new generic method to get TushareEntityList<Stock> directly
    let stock_list: TushareEntityList<Stock> = client.call_api_as(request).await?;

    // Display the results
    println!("Found {} stocks:", stock_list.len());
    for (i, stock) in stock_list.iter().take(10).enumerate() {
        println!("{}. {} ({}) - {}", i + 1, stock.ts_code, stock.symbol, stock.name);
    }

    if stock_list.len() > 10 {
        println!("... and {} more stocks", stock_list.len() - 10);
    }
    
    // Show pagination info
    println!("Total records: {}", stock_list.count());
    println!("Has more pages: {}", stock_list.has_more());

    Ok(())
}

examples/simple_stock_conversion.rs (line 14)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client (you need to set TUSHARE_TOKEN environment variable)
    let client = TushareClient::from_env()?;

    // Create request for stock basic data
    let request = request!(Api::StockBasic, {
        "list_status" => "L"
    }, [
        "ts_code", "symbol", "name"
    ]);

    // Method 1: Use the generic call_api_as method with TushareEntityList
    println!("=== Method 1: Using call_api_as with TushareEntityList ===");
    let stock_list: TushareEntityList<Stock> = client.call_api_as(request.clone()).await?;
    
    println!("Found {} stocks:", stock_list.len());
    for (i, stock) in stock_list.iter().take(5).enumerate() {
        println!("{}. {} ({}) - {}", i + 1, stock.ts_code, stock.symbol, stock.name);
    }
    
    // Show pagination info
    println!("Total records: {}", stock_list.count());
    println!("Has more pages: {}", stock_list.has_more());

    // Method 2: Use the traditional call_api and manual conversion
    println!("\n=== Method 2: Using call_api + manual conversion ===");
    let response = client.call_api(&request).await?;
    let stocks: Vec<Stock> = tushare_api::utils::response_to_vec(response)?;
    
    println!("Found {} stocks:", stocks.len());
    for (i, stock) in stocks.iter().take(5).enumerate() {
        println!("{}. {} ({}) - {}", i + 1, stock.ts_code, stock.symbol, stock.name);
    }

    Ok(())
}

examples/custom_type_example.rs (line 116)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Set up logging
    env_logger::init();
    
    // Create client from environment variable
    let client = TushareClient::from_env()?;
    
    // Create request for daily stock data
    let request = TushareRequest::new(
        Api::Daily,
        params![
            "ts_code" => "000001.SZ",
            "start_date" => "20240101",
            "end_date" => "20240131"
        ],
        fields![
            "ts_code", "trade_date", "open", "high", "low", "close", "vol", "amount"
        ]
    );
    
    println!("Fetching daily stock data with custom Decimal types...");
    
    // Call API and get typed response with automatic conversion
    let stock_prices: TushareEntityList<StockPrice> = client.call_api_as(request).await?;
    
    println!("Retrieved {} stock price records", stock_prices.len());
    println!("Has more data: {}", stock_prices.has_more());
    println!("Total count: {}", stock_prices.count());
    
    // Display first few records
    for (i, price) in stock_prices.iter().take(5).enumerate() {
        println!("\nRecord {}:", i + 1);
        println!("  Stock Code: {}", price.ts_code);
        println!("  Trade Date: {}", price.trade_date);
        println!("  Open Price: {}", price.open_price);
        println!("  High Price: {}", price.high_price);
        println!("  Low Price: {}", price.low_price);
        println!("  Close Price: {}", price.close_price);
        
        if let Some(vol) = &price.volume {
            println!("  Volume: {}", vol);
        }
        
        if let Some(amount) = &price.amount {
            println!("  Amount: {}", amount);
        }
    }
    
    Ok(())
}

examples/macro_conversion_example.rs (line 88)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建客户端
    let client = TushareClient::from_env()?;

    println!("=== 示例1: 使用 FromTushareData 派生宏获取股票基本信息 ===");
    
    let request = request!(Api::StockBasic, {
        "list_status" => "L"
    }, [
        "ts_code", "symbol", "name", "area", "industry", "market", "list_date"
    ]);

    // 直接获取 TushareEntityList<Stock> 类型
    let stock_list: TushareEntityList<Stock> = client.call_api_as(request).await?;
    
    println!("找到 {} 只股票:", stock_list.len());
    for (i, stock) in stock_list.iter().take(5).enumerate() {
        println!("{}. {} ({}) - {} [{}] {}", 
            i + 1, 
            stock.ts_code, 
            stock.symbol, 
            stock.name,
            stock.area.as_deref().unwrap_or("未知"),
            stock.industry.as_deref().unwrap_or("未知行业")
        );
    }
    
    // 显示分页信息
    println!("总记录数: {}, 是否有更多页面: {}", stock_list.count(), stock_list.has_more());

    println!("\n=== 示例2: 获取简单股票信息 ===");
    
    let simple_request = request!(Api::StockBasic, {
        "list_status" => "L"
    }, [
        "ts_code", "symbol", "name"
    ]);

    let simple_stock_list: TushareEntityList<SimpleStock> = client.call_api_as(simple_request).await?;
    
    println!("找到 {} 只股票 (简化版):", simple_stock_list.len());
    for (i, stock) in simple_stock_list.iter().take(3).enumerate() {
        println!("{}. {} ({}) - {}", i + 1, stock.ts_code, stock.symbol, stock.name);
    }

    println!("\n=== 示例3: 获取基金信息 ===");
    
    let fund_request = request!(Api::FundBasic, {
        "market" => "E"
    }, [
        "ts_code", "name", "management", "custodian", "fund_type", "found_date", "list_date", "status"
    ]);

    let fund_list: TushareEntityList<Fund> = client.call_api_as(fund_request).await?;
    
    println!("找到 {} 只基金:", fund_list.len());
    for (i, fund) in fund_list.iter().take(3).enumerate() {
        println!("{}. {} - {} [{}] 管理人: {}", 
            i + 1, 
            fund.ts_code, 
            fund.name,
            fund.fund_type.as_deref().unwrap_or("未知类型"),
            fund.management.as_deref().unwrap_or("未知")
        );
    }

    Ok(())
}

examples/env_usage.rs (line 9)

async fn main() -> TushareResult<()> {
    println!("=== 使用环境变量 TUSHARE_TOKEN 创建客户端 ===");
    
    // 从环境变量创建客户端（使用默认超时设置）
    let client = match TushareClient::from_env() {
        Ok(client) => {
            println!("✅ 成功从环境变量 TUSHARE_TOKEN 创建客户端");
            client
        }
        Err(e) => {
            eprintln!("❌ 无法从环境变量创建客户端: {}", e);
            eprintln!("请确保设置了环境变量 TUSHARE_TOKEN");
            eprintln!("例如: export TUSHARE_TOKEN=your_token_here");
            return Err(e);
        }
    };
    
    // 使用宏构建请求（支持直接使用字符串字面量）
    let request = TushareRequest {
        api_name: Api::StockBasic,
        params: params!("list_status" => "L"),
        fields: fields!["ts_code", "name", "industry", "area"],
    };
    
    // 调用 API
    match client.call_api(&request).await {
        Ok(response) => {
            if let Some(data) = response.data {
                println!("✅ 成功获取到 {} 条记录", data.items.len());

                // 显示前5条记录
                println!("\n前5条股票信息:");
                for (i, item) in data.items.iter().take(5).enumerate() {
                    println!("{}. {:?}", i + 1, item);
                }
            }
        }
        Err(e) => {
            eprintln!("❌ 获取股票列表失败: {}", e);
        }
    }
    
    println!("\n=== 使用环境变量和自定义超时设置 ===");
    
    // 从环境变量创建客户端（自定义超时设置）
    let client_with_timeout = TushareClient::from_env_with_timeout(
        Duration::from_secs(5),  // 连接超时 5 秒
        Duration::from_secs(60)  // 请求超时 60 秒
    )?;
    
    println!("\n=== 演示自定义 API 调用 ===\n");
    
    let custom_request = TushareRequest {
        api_name: Api::Custom("daily".to_string()),
        params: params!("ts_code" => "000001.SZ"),
        fields: fields!["ts_code", "trade_date", "close"],
    };
    
    match client_with_timeout.call_api(&custom_request).await {
        Ok(response) => {
            if let Some(data) = response.data {
                if let Some(item) = data.items.first() {
                    println!("✅ 找到股票信息:");
                    for (field, value) in data.fields.iter().zip(item.iter()) {
                        println!("  {}: {}", field, value);
                    }
                } else {
                    println!("未找到该股票");
                }
            }
        }
        Err(e) => {
            eprintln!("❌ 查询股票失败: {}", e);
        }
    }

    Ok(())
}

pub fn from_env_with_timeout( connect_timeout: Duration, timeout: Duration, ) -> TushareResult<Self>

Create a new Tushare client from TUSHARE_TOKEN environment variable with custom timeout settings

Arguments

• connect_timeout - Connection timeout duration
• timeout - Request timeout duration

Errors

Returns TushareError::InvalidToken if TUSHARE_TOKEN environment variable does not exist or is empty

Example

use tushare_api::{TushareClient, TushareResult};
use std::time::Duration;
 
// Requires TUSHARE_TOKEN environment variable to be set
let client = TushareClient::from_env_with_timeout(
    Duration::from_secs(5),  // Connection timeout 5 seconds
    Duration::from_secs(60)  // Request timeout 60 seconds
)?;

Examples found in repository

examples/env_usage.rs (lines 50-53)

async fn main() -> TushareResult<()> {
    println!("=== 使用环境变量 TUSHARE_TOKEN 创建客户端 ===");
    
    // 从环境变量创建客户端（使用默认超时设置）
    let client = match TushareClient::from_env() {
        Ok(client) => {
            println!("✅ 成功从环境变量 TUSHARE_TOKEN 创建客户端");
            client
        }
        Err(e) => {
            eprintln!("❌ 无法从环境变量创建客户端: {}", e);
            eprintln!("请确保设置了环境变量 TUSHARE_TOKEN");
            eprintln!("例如: export TUSHARE_TOKEN=your_token_here");
            return Err(e);
        }
    };
    
    // 使用宏构建请求（支持直接使用字符串字面量）
    let request = TushareRequest {
        api_name: Api::StockBasic,
        params: params!("list_status" => "L"),
        fields: fields!["ts_code", "name", "industry", "area"],
    };
    
    // 调用 API
    match client.call_api(&request).await {
        Ok(response) => {
            if let Some(data) = response.data {
                println!("✅ 成功获取到 {} 条记录", data.items.len());

                // 显示前5条记录
                println!("\n前5条股票信息:");
                for (i, item) in data.items.iter().take(5).enumerate() {
                    println!("{}. {:?}", i + 1, item);
                }
            }
        }
        Err(e) => {
            eprintln!("❌ 获取股票列表失败: {}", e);
        }
    }
    
    println!("\n=== 使用环境变量和自定义超时设置 ===");
    
    // 从环境变量创建客户端（自定义超时设置）
    let client_with_timeout = TushareClient::from_env_with_timeout(
        Duration::from_secs(5),  // 连接超时 5 秒
        Duration::from_secs(60)  // 请求超时 60 秒
    )?;
    
    println!("\n=== 演示自定义 API 调用 ===\n");
    
    let custom_request = TushareRequest {
        api_name: Api::Custom("daily".to_string()),
        params: params!("ts_code" => "000001.SZ"),
        fields: fields!["ts_code", "trade_date", "close"],
    };
    
    match client_with_timeout.call_api(&custom_request).await {
        Ok(response) => {
            if let Some(data) = response.data {
                if let Some(item) = data.items.first() {
                    println!("✅ 找到股票信息:");
                    for (field, value) in data.fields.iter().zip(item.iter()) {
                        println!("  {}: {}", field, value);
                    }
                } else {
                    println!("未找到该股票");
                }
            }
        }
        Err(e) => {
            eprintln!("❌ 查询股票失败: {}", e);
        }
    }

    Ok(())
}

pub fn with_timeout( token: &str, connect_timeout: Duration, timeout: Duration, ) -> Self

Create a new Tushare client with custom timeout settings

Arguments

• token - Tushare API Token
• connect_timeout - Connection timeout duration
• timeout - Request timeout duration

Example

use tushare_api::TushareClient;
use std::time::Duration;
 
let client = TushareClient::with_timeout(
    "your_token_here",
    Duration::from_secs(5),  // Connection timeout 5 seconds
    Duration::from_secs(60)  // Request timeout 60 seconds
);

Examples found in repository

examples/basic_usage.rs (lines 43-47)

async fn main() -> TushareResult<()> {
    // 从环境变量获取 token
    let token = env::var("TUSHARE_TOKEN")
        .expect("请设置环境变量 TUSHARE_TOKEN");

    // 创建客户端（使用默认超时设置）
    let client = TushareClient::new(&token);
    
    println!("=== 使用默认超时设置获取股票基本信息 ===");
    
    let request = TushareRequest {
        api_name: Api::StockBasic,
        params: params!("list_status" => "L"),
        fields: fields!["ts_code", "name", "industry", "area"],
    };
    
    match client.call_api(&request).await {
        Ok(response) => {
            if let Some(data) = response.data {
                println!("成功获取到 {} 条记录", data.items.len());

                // 显示前10条记录
                println!("\n前10条股票信息:");
                for (i, item) in data.items.iter().take(10).enumerate() {
                    println!("{}. {:?}", i + 1, item);
                }
            }
        }
        Err(e) => {
            eprintln!("获取股票列表失败: {}", e);
        }
    }
    
    println!("\n=== 使用自定义超时设置查询特定股票 ===");
    
    // 创建客户端（自定义超时设置）
    let client_with_timeout = TushareClient::with_timeout(
        &token,
        Duration::from_secs(5),  // 连接超时 5 秒
        Duration::from_secs(60)  // 请求超时 60 秒
    );
    
    let mut stock_params = HashMap::new();
    stock_params.insert("ts_code".into(), "000001.SZ".into());
    
    let stock_request = TushareRequest {
        api_name: Api::StockBasic,
        params: stock_params,
        fields: vec![
            "ts_code".into(),
            "symbol".into(),
            "name".into(),
            "area".into(),
            "industry".into(),
            "list_date".into(),
        ],
    };
    
    match client_with_timeout.call_api(&stock_request).await {
        Ok(response) => {
            if let Some(data) = response.data {
                if let Some(item) = data.items.first() {
                    println!("找到股票信息:");
                    for (field, value) in data.fields.iter().zip(item.iter()) {
                        println!("  {}: {}", field, value);
                    }
                } else {
                    println!("未找到该股票");
                }
            }
        }
        Err(e) => {
            eprintln!("查询股票失败: {}", e);
        }
    }

    Ok(())
}

pub async fn call_api<T>(&self, request: &T) -> TushareResult<TushareResponse>

where for<'a> &'a T: TryInto<TushareRequest>, for<'a> <&'a T as TryInto<TushareRequest>>::Error: Into<TushareError>,

Call Tushare API with flexible string types support

Arguments

• request - API request parameters, supports direct use of string literals

Returns

Returns API response result

Example

use tushare_api::{TushareClient, TushareRequest, Api, params, fields, request};
 
    let client = TushareClient::new("your_token_here");
     
    // Now you can use string literals directly!
    let request = request!(Api::StockBasic, {
        "list_status" => "L"
    }, [
        "ts_code", "name"
    ]);
     
    let response = client.call_api(&request).await?;
    println!("Response: {:?}", response);

Examples found in repository

examples/simple_stock_conversion.rs (line 38)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client (you need to set TUSHARE_TOKEN environment variable)
    let client = TushareClient::from_env()?;

    // Create request for stock basic data
    let request = request!(Api::StockBasic, {
        "list_status" => "L"
    }, [
        "ts_code", "symbol", "name"
    ]);

    // Method 1: Use the generic call_api_as method with TushareEntityList
    println!("=== Method 1: Using call_api_as with TushareEntityList ===");
    let stock_list: TushareEntityList<Stock> = client.call_api_as(request.clone()).await?;
    
    println!("Found {} stocks:", stock_list.len());
    for (i, stock) in stock_list.iter().take(5).enumerate() {
        println!("{}. {} ({}) - {}", i + 1, stock.ts_code, stock.symbol, stock.name);
    }
    
    // Show pagination info
    println!("Total records: {}", stock_list.count());
    println!("Has more pages: {}", stock_list.has_more());

    // Method 2: Use the traditional call_api and manual conversion
    println!("\n=== Method 2: Using call_api + manual conversion ===");
    let response = client.call_api(&request).await?;
    let stocks: Vec<Stock> = tushare_api::utils::response_to_vec(response)?;
    
    println!("Found {} stocks:", stocks.len());
    for (i, stock) in stocks.iter().take(5).enumerate() {
        println!("{}. {} ({}) - {}", i + 1, stock.ts_code, stock.symbol, stock.name);
    }

    Ok(())
}

examples/generic_api_usage.rs (line 23)

async fn main() -> TushareResult<()> {
    // 从环境变量获取 Tushare token
    let token = env::var("TUSHARE_TOKEN")
        .expect("请设置环境变量 TUSHARE_TOKEN");

    // 创建客户端
    let client = TushareClient::new(&token);

    println!("=== 使用通用 API 方法获取股票列表 ===");
    
    // 使用宏构建请求（支持直接使用字符串字面量）
    let request = TushareRequest {
        api_name: Api::StockBasic,
        params: params!("list_status" => "L"),
        fields: fields!["ts_code", "symbol", "name", "area", "industry", "list_date"],
    };
    
    // 调用通用 API 方法
    let response = client.call_api(&request).await?;
    
    println!("API 调用成功！");
    println!("请求 ID: {}", response.request_id);
    println!("返回码: {}", response.code);
    if let Some(data) = response.data {
        println!("返回字段: {:?}", data.fields);
        println!("数据条数: {}", data.items.len());
        
        // 显示前5条记录
        println!("\n前5条股票记录:");
        for (i, item) in data.items.iter().take(5).enumerate() {
            println!("{}. {:?}", i + 1, item);
        }
    }
    
    println!("\n=== 使用通用 API 方法查询特定股票 ===");
    
    // 查询特定股票
    let request = TushareRequest {
        api_name: Api::StockBasic,
        params: params!("ts_code" => "000001.SZ"),
        fields: fields!["ts_code", "name", "industry", "market", "list_date"],
    };
    
    let response = client.call_api(&request).await?;

    if let Some(data) = response.data {
        if let Some(stock_data) = data.items.first() {
            println!("找到股票信息:");
            for (field, value) in data.fields.iter().zip(stock_data.iter()) {
                println!("  {}: {}", field, value);
            }
        } else {
            println!("未找到该股票");
        }
    }

    Ok(())
}

examples/basic_usage.rs (line 23)

async fn main() -> TushareResult<()> {
    // 从环境变量获取 token
    let token = env::var("TUSHARE_TOKEN")
        .expect("请设置环境变量 TUSHARE_TOKEN");

    // 创建客户端（使用默认超时设置）
    let client = TushareClient::new(&token);
    
    println!("=== 使用默认超时设置获取股票基本信息 ===");
    
    let request = TushareRequest {
        api_name: Api::StockBasic,
        params: params!("list_status" => "L"),
        fields: fields!["ts_code", "name", "industry", "area"],
    };
    
    match client.call_api(&request).await {
        Ok(response) => {
            if let Some(data) = response.data {
                println!("成功获取到 {} 条记录", data.items.len());

                // 显示前10条记录
                println!("\n前10条股票信息:");
                for (i, item) in data.items.iter().take(10).enumerate() {
                    println!("{}. {:?}", i + 1, item);
                }
            }
        }
        Err(e) => {
            eprintln!("获取股票列表失败: {}", e);
        }
    }
    
    println!("\n=== 使用自定义超时设置查询特定股票 ===");
    
    // 创建客户端（自定义超时设置）
    let client_with_timeout = TushareClient::with_timeout(
        &token,
        Duration::from_secs(5),  // 连接超时 5 秒
        Duration::from_secs(60)  // 请求超时 60 秒
    );
    
    let mut stock_params = HashMap::new();
    stock_params.insert("ts_code".into(), "000001.SZ".into());
    
    let stock_request = TushareRequest {
        api_name: Api::StockBasic,
        params: stock_params,
        fields: vec![
            "ts_code".into(),
            "symbol".into(),
            "name".into(),
            "area".into(),
            "industry".into(),
            "list_date".into(),
        ],
    };
    
    match client_with_timeout.call_api(&stock_request).await {
        Ok(response) => {
            if let Some(data) = response.data {
                if let Some(item) = data.items.first() {
                    println!("找到股票信息:");
                    for (field, value) in data.fields.iter().zip(item.iter()) {
                        println!("  {}: {}", field, value);
                    }
                } else {
                    println!("未找到该股票");
                }
            }
        }
        Err(e) => {
            eprintln!("查询股票失败: {}", e);
        }
    }

    Ok(())
}

examples/env_usage.rs (line 30)

async fn main() -> TushareResult<()> {
    println!("=== 使用环境变量 TUSHARE_TOKEN 创建客户端 ===");
    
    // 从环境变量创建客户端（使用默认超时设置）
    let client = match TushareClient::from_env() {
        Ok(client) => {
            println!("✅ 成功从环境变量 TUSHARE_TOKEN 创建客户端");
            client
        }
        Err(e) => {
            eprintln!("❌ 无法从环境变量创建客户端: {}", e);
            eprintln!("请确保设置了环境变量 TUSHARE_TOKEN");
            eprintln!("例如: export TUSHARE_TOKEN=your_token_here");
            return Err(e);
        }
    };
    
    // 使用宏构建请求（支持直接使用字符串字面量）
    let request = TushareRequest {
        api_name: Api::StockBasic,
        params: params!("list_status" => "L"),
        fields: fields!["ts_code", "name", "industry", "area"],
    };
    
    // 调用 API
    match client.call_api(&request).await {
        Ok(response) => {
            if let Some(data) = response.data {
                println!("✅ 成功获取到 {} 条记录", data.items.len());

                // 显示前5条记录
                println!("\n前5条股票信息:");
                for (i, item) in data.items.iter().take(5).enumerate() {
                    println!("{}. {:?}", i + 1, item);
                }
            }
        }
        Err(e) => {
            eprintln!("❌ 获取股票列表失败: {}", e);
        }
    }
    
    println!("\n=== 使用环境变量和自定义超时设置 ===");
    
    // 从环境变量创建客户端（自定义超时设置）
    let client_with_timeout = TushareClient::from_env_with_timeout(
        Duration::from_secs(5),  // 连接超时 5 秒
        Duration::from_secs(60)  // 请求超时 60 秒
    )?;
    
    println!("\n=== 演示自定义 API 调用 ===\n");
    
    let custom_request = TushareRequest {
        api_name: Api::Custom("daily".to_string()),
        params: params!("ts_code" => "000001.SZ"),
        fields: fields!["ts_code", "trade_date", "close"],
    };
    
    match client_with_timeout.call_api(&custom_request).await {
        Ok(response) => {
            if let Some(data) = response.data {
                if let Some(item) = data.items.first() {
                    println!("✅ 找到股票信息:");
                    for (field, value) in data.fields.iter().zip(item.iter()) {
                        println!("  {}: {}", field, value);
                    }
                } else {
                    println!("未找到该股票");
                }
            }
        }
        Err(e) => {
            eprintln!("❌ 查询股票失败: {}", e);
        }
    }

    Ok(())
}

examples/tracing_example.rs (line 69)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== Tushare API Tracing Integration Example ===");
    
    // Method 1: Using tracing-log bridge (recommended for mixed ecosystems)
    #[cfg(all(feature = "tracing", feature = "tracing-log"))] 
    {
        println!("\n--- Method 1: Using tracing-log bridge ---");
        use tracing_subscriber;
        use tracing_log::LogTracer;
        
        // Initialize log-to-tracing bridge
        LogTracer::init()?;
        
        // Set up tracing subscriber
        tracing_subscriber::fmt()
            .with_env_filter("debug")
            .with_target(false)
            .with_thread_ids(true)
            .with_level(true)
            .with_max_level(tracing::Level::DEBUG)
            .init();
    }
    
    // Method 2: Using native tracing feature (when library is compiled with tracing feature)
    #[cfg(feature = "tracing")]
    {
        println!("\n--- Method 2: Using native tracing feature ---");
        println!("库和用户程序都使用 tracing\n");
        
        // 直接初始化 tracing subscriber
        tracing_subscriber::fmt()
            .with_max_level(tracing::Level::DEBUG)
            .init();
    }

    println!("初始化 Tushare 客户端...");
    
    let client = TushareClient::builder()
        .with_token("demo_token_for_testing")
        .with_log_level(LogLevel::Debug)
        .log_requests(true)
        .log_responses(false)
        .log_performance(true)
        .build()?;

    println!("创建测试请求...");
    
    let mut params = HashMap::new();
    params.insert("list_status".to_string(), "L".to_string());
    
    let request = TushareRequest {
        api_name: Api::StockBasic,
        params,
        fields: vec!["ts_code".to_string(), "name".to_string()],
    };

    println!("发送 API 请求（注意观察日志输出）...");
    
    // 这会触发我们库的日志输出
    match client.call_api(&request).await {
        Ok(_response) => {
            println!("✅ API 调用成功（实际会因为 token 无效而失败，但能看到日志）");
        }
        Err(e) => {
            println!("❌ API 调用失败（预期行为）: {}", e);
        }
    }

    #[cfg(not(feature = "tracing"))]
    {
        println!("\n--- Tracing feature not enabled ---");
        println!("To enable tracing support, compile with: cargo build --features tracing");
        println!("Or add tracing-log bridge support with: cargo build --features tracing-log");
    }

    println!("\n=== 总结 ===");
    #[cfg(feature = "tracing")]
    println!("✅ 使用了原生 tracing 支持，日志输出更加结构化");
    
    #[cfg(not(feature = "tracing"))]
    println!("✅ 使用了 tracing-log 桥接，成功捕获了库的 log 输出");

    Ok(())
}

examples/logging_example.rs (line 80)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 注意：在实际使用中，您需要初始化一个日志记录器（如 env_logger）
    // env_logger::init();

    println!("=== Tushare API 日志功能演示 ===\n");

    // 示例 1: 使用默认日志配置
    println!("1. 使用默认日志配置:");
    let client1 = TushareClient::builder()
        .with_token("your_token_here")
        .build()?;

    // 示例 2: 自定义日志级别
    println!("\n2. 自定义日志级别为 Debug:");
    let client2 = TushareClient::builder()
        .with_token("your_token_here")
        .with_log_level(LogLevel::Debug)
        .build()?;

    // 示例 3: 详细的日志配置
    println!("\n3. 详细的日志配置:");
    let client3 = TushareClient::builder()
        .with_token("your_token_here")
        .with_log_level(LogLevel::Trace)
        .log_requests(true)
        .log_responses(true)
        .log_sensitive_data(false) // 生产环境建议设为 false
        .log_performance(true)
        .with_connect_timeout(Duration::from_secs(5))
        .with_timeout(Duration::from_secs(30))
        .build()?;

    // 示例 4: 使用自定义 LogConfig
    println!("\n4. 使用自定义 LogConfig:");
    let log_config = LogConfig {
        level: LogLevel::Info,
        log_requests: true,
        log_responses: false,
        log_responses_err: true,
        log_sensitive_data: false,
        log_performance: true,
    };
    
    let client4 = TushareClient::builder()
        .with_token("your_token_here")
        .with_log_config(log_config)
        .build()?;

    // 示例 5: 关闭日志
    println!("\n5. 关闭日志:");
    let client5 = TushareClient::builder()
        .with_token("your_token_here")
        .with_log_level(LogLevel::Off)
        .build()?;

    // 演示 API 调用（需要有效的 token）
    if std::env::var("TUSHARE_TOKEN").is_ok() {
        println!("\n=== 实际 API 调用演示 ===");
        
        let client = TushareClient::builder()
            .with_token(&std::env::var("TUSHARE_TOKEN")?)
            .with_log_level(LogLevel::Info)
            .log_performance(true)
            .build()?;

        let mut params = HashMap::new();
        params.insert("list_status".to_string(), "L".to_string());
        
        let req = TushareRequest {
            api_name: Api::StockBasic,
            params,
            fields: vec!["ts_code".to_string(), "name".to_string()],
        };

        match client.call_api(&req).await {
            Ok(response) => {
                if let Some(data) = response.data {
                    println!("✅ API 调用成功，返回 {} 条记录", data.items.len());
                }
            }
            Err(e) => {
                println!("❌ API 调用失败: {}", e);
            }
        }
    } else {
        println!("\n💡 提示: 设置 TUSHARE_TOKEN 环境变量以查看实际的 API 调用日志");
    }

    println!("\n=== 日志级别说明 ===");
    println!("• Off    - 关闭所有日志");
    println!("• Error  - 只记录错误信息");
    println!("• Warn   - 记录错误和警告");
    println!("• Info   - 记录基本信息（推荐）");
    println!("• Debug  - 记录详细调试信息");
    println!("• Trace  - 记录所有信息包括原始数据");

    println!("\n=== 日志配置选项说明 ===");
    println!("• log_requests      - 是否记录请求参数");
    println!("• log_responses     - 是否记录响应内容（可能很大）");
    println!("• log_sensitive_data - 是否记录敏感数据（如 token）");
    println!("• log_performance   - 是否记录性能指标（耗时等）");

    Ok(())
}

pub async fn call_api_as<T, R>( &self, request: R, ) -> TushareResult<TushareEntityList<T>>

where T: FromTushareData, for<'a> &'a R: TryInto<TushareRequest>, for<'a> <&'a R as TryInto<TushareRequest>>::Error: Into<TushareError>,

调用 Tushare API，并将响应的 data.items 解析为强类型的 TushareEntityList<T>。

这是 Self::call_api 的便捷封装：先执行请求，再把响应转换为实体列表。

Type Parameters

• T: 单行数据对应的实体类型（需要实现 crate::traits::FromTushareData）。
• R: 请求类型（需要实现 TryInto<TushareRequest>），通常可由参数自动推导。

Errors

• 请求构造失败、网络/HTTP 错误、JSON/数据映射失败等都会以 TushareError 返回。

Example

let client = TushareClient::from_env()?;
let stocks: TushareEntityList<Stock> = client
    .call_api_as(request!(Api::StockBasic, {}, ["ts_code"]))
    .await?;

Examples found in repository

examples/stock_conversion_example.rs (line 24)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client (you need to set TUSHARE_TOKEN environment variable)
    let client = TushareClient::from_env()?;

    // Create request for stock basic data
    let request = request!(Api::StockBasic, {
        "list_status" => "L"
    }, [
        "ts_code", "symbol", "name"
    ]);

    // Use the new generic method to get TushareEntityList<Stock> directly
    let stock_list: TushareEntityList<Stock> = client.call_api_as(request).await?;

    // Display the results
    println!("Found {} stocks:", stock_list.len());
    for (i, stock) in stock_list.iter().take(10).enumerate() {
        println!("{}. {} ({}) - {}", i + 1, stock.ts_code, stock.symbol, stock.name);
    }

    if stock_list.len() > 10 {
        println!("... and {} more stocks", stock_list.len() - 10);
    }
    
    // Show pagination info
    println!("Total records: {}", stock_list.count());
    println!("Has more pages: {}", stock_list.has_more());

    Ok(())
}

examples/simple_stock_conversion.rs (line 25)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client (you need to set TUSHARE_TOKEN environment variable)
    let client = TushareClient::from_env()?;

    // Create request for stock basic data
    let request = request!(Api::StockBasic, {
        "list_status" => "L"
    }, [
        "ts_code", "symbol", "name"
    ]);

    // Method 1: Use the generic call_api_as method with TushareEntityList
    println!("=== Method 1: Using call_api_as with TushareEntityList ===");
    let stock_list: TushareEntityList<Stock> = client.call_api_as(request.clone()).await?;
    
    println!("Found {} stocks:", stock_list.len());
    for (i, stock) in stock_list.iter().take(5).enumerate() {
        println!("{}. {} ({}) - {}", i + 1, stock.ts_code, stock.symbol, stock.name);
    }
    
    // Show pagination info
    println!("Total records: {}", stock_list.count());
    println!("Has more pages: {}", stock_list.has_more());

    // Method 2: Use the traditional call_api and manual conversion
    println!("\n=== Method 2: Using call_api + manual conversion ===");
    let response = client.call_api(&request).await?;
    let stocks: Vec<Stock> = tushare_api::utils::response_to_vec(response)?;
    
    println!("Found {} stocks:", stocks.len());
    for (i, stock) in stocks.iter().take(5).enumerate() {
        println!("{}. {} ({}) - {}", i + 1, stock.ts_code, stock.symbol, stock.name);
    }

    Ok(())
}

examples/custom_type_example.rs (line 134)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Set up logging
    env_logger::init();
    
    // Create client from environment variable
    let client = TushareClient::from_env()?;
    
    // Create request for daily stock data
    let request = TushareRequest::new(
        Api::Daily,
        params![
            "ts_code" => "000001.SZ",
            "start_date" => "20240101",
            "end_date" => "20240131"
        ],
        fields![
            "ts_code", "trade_date", "open", "high", "low", "close", "vol", "amount"
        ]
    );
    
    println!("Fetching daily stock data with custom Decimal types...");
    
    // Call API and get typed response with automatic conversion
    let stock_prices: TushareEntityList<StockPrice> = client.call_api_as(request).await?;
    
    println!("Retrieved {} stock price records", stock_prices.len());
    println!("Has more data: {}", stock_prices.has_more());
    println!("Total count: {}", stock_prices.count());
    
    // Display first few records
    for (i, price) in stock_prices.iter().take(5).enumerate() {
        println!("\nRecord {}:", i + 1);
        println!("  Stock Code: {}", price.ts_code);
        println!("  Trade Date: {}", price.trade_date);
        println!("  Open Price: {}", price.open_price);
        println!("  High Price: {}", price.high_price);
        println!("  Low Price: {}", price.low_price);
        println!("  Close Price: {}", price.close_price);
        
        if let Some(vol) = &price.volume {
            println!("  Volume: {}", vol);
        }
        
        if let Some(amount) = &price.amount {
            println!("  Amount: {}", amount);
        }
    }
    
    Ok(())
}

examples/macro_conversion_example.rs (line 99)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建客户端
    let client = TushareClient::from_env()?;

    println!("=== 示例1: 使用 FromTushareData 派生宏获取股票基本信息 ===");
    
    let request = request!(Api::StockBasic, {
        "list_status" => "L"
    }, [
        "ts_code", "symbol", "name", "area", "industry", "market", "list_date"
    ]);

    // 直接获取 TushareEntityList<Stock> 类型
    let stock_list: TushareEntityList<Stock> = client.call_api_as(request).await?;
    
    println!("找到 {} 只股票:", stock_list.len());
    for (i, stock) in stock_list.iter().take(5).enumerate() {
        println!("{}. {} ({}) - {} [{}] {}", 
            i + 1, 
            stock.ts_code, 
            stock.symbol, 
            stock.name,
            stock.area.as_deref().unwrap_or("未知"),
            stock.industry.as_deref().unwrap_or("未知行业")
        );
    }
    
    // 显示分页信息
    println!("总记录数: {}, 是否有更多页面: {}", stock_list.count(), stock_list.has_more());

    println!("\n=== 示例2: 获取简单股票信息 ===");
    
    let simple_request = request!(Api::StockBasic, {
        "list_status" => "L"
    }, [
        "ts_code", "symbol", "name"
    ]);

    let simple_stock_list: TushareEntityList<SimpleStock> = client.call_api_as(simple_request).await?;
    
    println!("找到 {} 只股票 (简化版):", simple_stock_list.len());
    for (i, stock) in simple_stock_list.iter().take(3).enumerate() {
        println!("{}. {} ({}) - {}", i + 1, stock.ts_code, stock.symbol, stock.name);
    }

    println!("\n=== 示例3: 获取基金信息 ===");
    
    let fund_request = request!(Api::FundBasic, {
        "market" => "E"
    }, [
        "ts_code", "name", "management", "custodian", "fund_type", "found_date", "list_date", "status"
    ]);

    let fund_list: TushareEntityList<Fund> = client.call_api_as(fund_request).await?;
    
    println!("找到 {} 只基金:", fund_list.len());
    for (i, fund) in fund_list.iter().take(3).enumerate() {
        println!("{}. {} - {} [{}] 管理人: {}", 
            i + 1, 
            fund.ts_code, 
            fund.name,
            fund.fund_type.as_deref().unwrap_or("未知类型"),
            fund.management.as_deref().unwrap_or("未知")
        );
    }

    Ok(())
}

Trait Implementations

impl Debug for TushareClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.