nargo_sdk/

lib.rs

#![warn(missing_docs)]

//! 前端SDK生成器模块
//!
//! 提供基于API元数据生成TypeScript前端SDK的功能。

use nargo_metadata::{ApiEndpoint, ApiMetadata, ApiParam, ApiParamType};
use std::{collections::HashMap, fs::File, io::Write, path::Path};

/// 前端SDK生成器
///
/// 负责根据API元数据生成TypeScript SDK
pub struct SdkGenerator;

impl SdkGenerator {
    /// 生成前端SDK
    ///
    /// # Arguments
    /// * `metadata` - API元数据
    /// * `output_dir` - 输出目录
    ///
    /// # Returns
    /// * `std::io::Result<()>` - 操作结果
    pub fn generate(metadata: &ApiMetadata, output_dir: &Path) -> std::io::Result<()> {
        std::fs::create_dir_all(output_dir)?;

        Self::generate_types(metadata, &output_dir.join("types.ts"))?;

        Self::generate_sdk(metadata, &output_dir.join("api.ts"))?;

        Ok(())
    }

    /// 生成类型定义文件
    ///
    /// # Arguments
    /// * `metadata` - API元数据
    /// * `output_path` - 输出文件路径
    ///
    /// # Returns
    /// * `std::io::Result<()>` - 操作结果
    fn generate_types(metadata: &ApiMetadata, output_path: &Path) -> std::io::Result<()> {
        let mut file = File::create(output_path)?;

        writeln!(file, "// Generated by Nargo SDK Generator")?;
        writeln!(file)?;

        for (name, type_def) in &metadata.types {
            writeln!(file, "export interface {name} {{")?;
            for field in &type_def.fields {
                let optional = if field.optional { "?" } else { "" };
                writeln!(file, "  {}{}: {};", field.name, optional, field.type_name)?;
            }
            writeln!(file, "}}")?;
            writeln!(file)?;
        }

        Ok(())
    }

    /// 生成SDK文件
    ///
    /// # Arguments
    /// * `metadata` - API元数据
    /// * `output_path` - 输出文件路径
    ///
    /// # Returns
    /// * `std::io::Result<()>` - 操作结果
    fn generate_sdk(metadata: &ApiMetadata, output_path: &Path) -> std::io::Result<()> {
        let mut file = File::create(output_path)?;

        writeln!(file, "/* eslint-disable */")?;
        writeln!(file, "// @ts-nocheck")?;
        writeln!(file, "import {{ useClient }} from '@nargo/client';")?;
        writeln!(file, "import type * as Types from './types';")?;
        writeln!(file)?;

        let mut controllers: HashMap<String, Vec<&ApiEndpoint>> = HashMap::new();
        for endpoint in &metadata.endpoints {
            controllers.entry(endpoint.controller.clone()).or_default().push(endpoint);
        }

        for (controller_name, endpoints) in controllers {
            Self::generate_controller(&mut file, &controller_name, &endpoints)?;
        }

        Ok(())
    }

    /// 生成控制器
    ///
    /// # Arguments
    /// * `file` - 输出文件
    /// * `controller_name` - 控制器名称
    /// * `endpoints` - 端点列表
    ///
    /// # Returns
    /// * `std::io::Result<()>` - 操作结果
    fn generate_controller(file: &mut File, controller_name: &str, endpoints: &[&ApiEndpoint]) -> std::io::Result<()> {
        writeln!(file, "export const {controller_name} = {{")?;

        for endpoint in endpoints {
            Self::generate_endpoint_method(file, controller_name, endpoint)?;
        }

        writeln!(file, "}};")?;
        writeln!(file)?;

        for endpoint in endpoints {
            Self::generate_endpoint_metadata(file, controller_name, endpoint)?;
        }
        writeln!(file)?;

        Ok(())
    }

    /// 生成端点方法
    ///
    /// # Arguments
    /// * `file` - 输出文件
    /// * `_controller_name` - 控制器名称
    /// * `endpoint` - API端点
    ///
    /// # Returns
    /// * `std::io::Result<()>` - 操作结果
    fn generate_endpoint_method(file: &mut File, _controller_name: &str, endpoint: &ApiEndpoint) -> std::io::Result<()> {
        let return_type = endpoint.return_type.as_deref().unwrap_or("any");

        writeln!(file, "  /**")?;
        writeln!(file, "   */")?;

        let params_str = Self::generate_params_list(&endpoint.params);
        writeln!(file, "  async {name}({params_str}): Promise<{return_type}> {{", name = endpoint.name)?;

        writeln!(file, "    const client = useClient();")?;

        let path = Self::generate_path(&endpoint.path, &endpoint.params);
        let query_params = Self::generate_query_params(&endpoint.params);
        let body_param = endpoint.params.iter().find(|p| p.param_type == ApiParamType::Body);
        let method = endpoint.method.to_lowercase();

        match method.as_str() {
            "get" | "delete" => {
                writeln!(file, "    return client.{}(`{}`, {{ params: {{ {} }} }});", method, path, query_params)?;
            }
            "post" | "put" | "patch" => {
                if let Some(body) = body_param {
                    writeln!(file, "    return client.{}(`{}`, {}, {{ params: {{ {} }} }});", method, path, body.name, query_params)?;
                }
                else {
                    writeln!(file, "    return client.{}(`{}`, undefined, {{ params: {{ {} }} }});", method, path, query_params)?;
                }
            }
            _ => {
                if let Some(body) = body_param {
                    writeln!(file, "    return client.{}(`{}`, {}, {{ params: {{ {} }} }});", method, path, body.name, query_params)?;
                }
                else {
                    writeln!(file, "    return client.{}(`{}`, {{ params: {{ {} }} }});", method, path, query_params)?;
                }
            }
        }

        writeln!(file, "  }},")?;

        Ok(())
    }

    /// 生成参数列表
    ///
    /// # Arguments
    /// * `params` - 参数列表
    ///
    /// # Returns
    /// * `String` - 参数列表字符串
    fn generate_params_list(params: &[ApiParam]) -> String {
        let filtered: Vec<String> = params.iter().filter(|p| p.param_type != ApiParamType::CurrentUser && p.param_type != ApiParamType::Session && p.param_type != ApiParamType::I18n).map(|p| format!("{}: {}", p.name, p.type_name)).collect();

        filtered.join(", ")
    }

    /// 生成路径字符串（替换路径参数）
    ///
    /// # Arguments
    /// * `path` - 原始路径
    /// * `params` - 参数列表
    ///
    /// # Returns
    /// * `String` - 替换后的路径字符串
    fn generate_path(path: &str, params: &[ApiParam]) -> String {
        let mut result = path.to_string();

        for param in params {
            if param.param_type == ApiParamType::Path {
                let placeholder = if let Some(extractor_param) = &param.extractor_param { format!(":{}", extractor_param) } else { format!(":{}", param.name) };
                result = result.replace(&placeholder, &format!("${{{}}}", param.name));
            }
        }

        result
    }

    /// 生成查询参数字符串
    ///
    /// # Arguments
    /// * `params` - 参数列表
    ///
    /// # Returns
    /// * `String` - 查询参数字符串
    fn generate_query_params(params: &[ApiParam]) -> String {
        let query_params: Vec<String> = params.iter().filter(|p| p.param_type == ApiParamType::Query).map(|p| p.name.clone()).collect();

        query_params.join(", ")
    }

    /// 生成端点元数据
    ///
    /// # Arguments
    /// * `file` - 输出文件
    /// * `controller_name` - 控制器名称
    /// * `endpoint` - API端点
    ///
    /// # Returns
    /// * `std::io::Result<()>` - 操作结果
    fn generate_endpoint_metadata(file: &mut File, controller_name: &str, endpoint: &ApiEndpoint) -> std::io::Result<()> {
        let nargo_id = format!("{}.{}", controller_name, endpoint.name);

        writeln!(file, "( {}.{} as any)._nargo_id = '{}';", controller_name, endpoint.name, nargo_id)?;
        writeln!(file, "( {}.{} as any).url = '{}';", controller_name, endpoint.name, endpoint.path)?;
        writeln!(file, "( {}.{} as any).method = '{}';", controller_name, endpoint.name, endpoint.method)?;

        Ok(())
    }
}