零基础掌握SmartCode：模板驱动代码生成实战指南

1. 什么是SmartCode？

当你需要重复编写CRUD代码时，是否感到枯燥？SmartCode就是解决这个问题的工具。它是一个基于.NET Core的代码生成工具，通过模板驱动的方式，帮你快速生成定制化代码结构。

简单说，SmartCode就像餐厅的自动点餐机：你选择模板（菜品），输入配置（口味要求），它就会输出成品代码（餐点）。

💡 小贴士：SmartCode支持多种数据库和编程语言，无论你用MySQL还是SQL Server，C#还是Java，它都能胜任。

2. 项目结构解析

SmartCode的目录结构就像图书馆的分类架，每个区域都有明确的功能定位：

SmartCode/
├── src/                  # 源代码区
│   ├── SmartCode/        # 核心功能模块
│   ├── SmartCode.App/    # 应用程序入口
│   ├── SmartCode.CLI/    # 命令行工具
│   ├── SmartCode.Db/     # 数据库操作模块
│   └── ...               # 其他功能模块
├── doc/                  # 文档资料区
├── Directory.Build.props # 项目全局配置
├── LICENSE               # 开源许可证
└── README.md             # 项目说明文档

2.1 核心模块介绍

• SmartCode.Generator：代码生成器，负责将模板和数据结合生成代码
• SmartCode.TemplateEngine：模板引擎，支持Razor和Handlebars模板
• SmartCode.ETL：数据抽取转换加载模块，处理数据流转

📌 关键文件路径：src/SmartCode.CLI/Program.cs是命令行入口，src/SmartCode.App/SmartCodeApp.cs是应用程序核心。

💡 小贴士：查看src/SmartCode/Configuration目录了解配置构建逻辑，这对自定义配置很有帮助。

3. 启动与运行流程

3.1 环境准备

在开始前，确保你的环境满足：

• .NET Core SDK
• 目标数据库（如SQL Server、MySQL等）
• Git工具

3.2 获取项目代码

git clone https://gitcode.com/gh_mirrors/smar/SmartCode
cd SmartCode

3.3 构建项目

dotnet build SmartCode.sln

3.4 运行命令行工具

cd src/SmartCode.CLI
dotnet run -- --help

运行成功后，你将看到命令行帮助信息，就像打开了工具箱，里面有各种可用工具。

💡 小贴士：使用dotnet run -- --project [配置文件]可以直接运行指定配置的代码生成任务。

4. 配置文件详解

配置文件是SmartCode的"食谱"，告诉它如何生成代码。默认配置文件为SmartCode.yml。

4.1 配置文件基本结构

Module: SmartSql.Starter
Author: Ahoo Wang
DataSource:
  Name: DB
  Provider: SqlServer
  ConnectionString: "Data Source=.;Initial Catalog=smartcodeDB;Integrated Security=True"
Language: CSharp
TemplateEngine: Razor
Output:
  Type: File
  Path: "E:/work/SmartSql-Starter"

4.2 核心配置项说明

配置项	必选/可选	描述	推荐值	注意事项
Module	必选	模块名称	项目功能相关名称	避免使用特殊字符
DataSource.Name	必选	数据源名称	DB	保持简洁明了
DataSource.Provider	必选	数据库提供器	SqlServer/MySql/PostgreSql	根据实际数据库选择
DataSource.ConnectionString	必选	数据库连接字符串	按数据库类型填写	确保有足够权限
Language	可选	目标语言	CSharp/Java/TypeScript	默认为CSharp
TemplateEngine	可选	模板引擎	Razor/Handlebars	Razor功能更强大
Output.Path	必选	输出路径	绝对路径	确保有写入权限

💡 小贴士：配置文件支持JSON和YAML格式，YAML更易读，推荐使用。

5. 模板使用指南

模板是SmartCode的"模具"，决定了生成代码的形状。

5.1 模板存放位置

模板文件位于src/SmartCode.Generator/RazorTemplates/目录下，按语言分类：

• CSharp模板：RazorTemplates/CSharp/
• Java模板：RazorTemplates/Java/
• TypeScript模板：RazorTemplates/TypeScript/

5.2 常用模板类型

• Entity.cshtml：实体类模板
• Repository.cshtml：仓储层模板
• Service.cshtml：服务层模板
• Controller.cshtml：控制器模板

📌 自定义模板步骤：

1. 复制现有模板文件
2. 修改内容以满足需求
3. 在配置文件中指定新模板路径

💡 小贴士：模板中使用@Model访问数据模型，例如@Model.TableName获取表名。

6. 常见误区

⚠️ 误区一：配置文件路径错误

• 症状：提示找不到配置文件
• 解决：使用绝对路径或确保相对路径正确

⚠️ 误区二：数据库连接字符串错误

• 症状：无法连接数据库
• 解决：检查服务器地址、数据库名、用户名和密码

⚠️ 误区三：模板语法错误

• 症状：生成代码异常或空白
• 解决：检查模板文件中的语法，特别是循环和条件判断部分

⚠️ 误区四：输出目录无写入权限

• 症状：生成失败，提示权限不足
• 解决：更换输出目录或修改目录权限

💡 小贴士：遇到问题时，先查看命令行输出的错误信息，通常能找到问题所在。

7. 高级功能：ETL数据处理

SmartCode不仅能生成代码，还能处理数据抽取、转换和加载（ETL）。

ETL配置文件示例：doc/SmartCode-ETL.yml，主要包含以下部分：

• Extract：数据抽取配置
• Transform：数据转换规则
• Load：数据加载目标

💡 小贴士：使用ETL功能可以实现不同数据库之间的数据迁移，或数据格式转换。

8. 总结

SmartCode是一个强大的代码生成工具，通过模板驱动的方式，帮助开发者减少重复劳动，提高工作效率。掌握它就像拥有了一把代码自动生成的钥匙，能打开快速开发的大门。

从配置文件到模板使用，从简单代码生成到复杂ETL处理，SmartCode都能胜任。开始尝试吧，让它为你的开发工作助力！

💡 小贴士：查看doc/common-problem.md了解更多常见问题及解决方案。