Util应用框架Web Api开发快速入门

本文是使用Util应用框架开发 Web Api 项目快速入门教程.

前面已经详细介绍了环境搭建,如果你还未准备好,请参考前文.

开发流程概述

创建代码生成专用数据库.

Util应用框架需要专门用来生成代码的数据库,该数据库仅用于代码生成.

约定 : 代码生成数据库应以 .Generator 结尾.

当然你也可以随意起名,但使用约定名称能更清晰的说明数据库用途.
使用配套代码生成器生成代码.

Util配套代码生成器连接到代码生成数据库,读取元数据,创建项目基架.

快速入门示例项目概述

项目名称: Demo
代码生成数据库名称: Demo.Generator

创建示例数据库

本文创建快速入门示例项目的代码生成数据库.

共提供三种数据库建库脚本,你只需选择一种即可.

创建 Sql Server 代码生成数据库

如果你使用Sql Server数据库,请按下面步骤创建Sql Server示例数据库和示例表.

创建 Demo.Generator 数据库

打开 SQL Server Management Studio ,新建数据库 Demo.Generator .

点击确定按钮,创建数据库.

添加示例表 Student

选中 Demo.Generator 数据库,点击 新建查询 按钮.

复制下面Sql语句,创建 Student 示例表.

Sql建库脚本通常使用 PowerDesigner 等数据建模工具生成.

sql 复制代码

CREATE TABLE [dbo].[Student](
	[StudentId] [uniqueidentifier] NOT NULL,
	[Name] [nvarchar](200) NOT NULL,
	[Gender] [int] NULL,
	[Age] [int] NULL,
	[Birthday] [datetime] NULL,
	[IdCard] [nvarchar](50) NULL,
	[Enabled] [bit] NOT NULL,
	[CreationTime] [datetime] NULL,
	[CreatorId] [uniqueidentifier] NULL,
	[LastModificationTime] [datetime] NULL,
	[LastModifierId] [uniqueidentifier] NULL,
	[IsDeleted] [bit] NOT NULL,
	[Version] [timestamp] NULL,
	[ExtraProperties] [nvarchar](max) NULL,
 CONSTRAINT [PK_STUDENT] PRIMARY KEY CLUSTERED 
(
	[StudentId] ASC
)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON, OPTIMIZE_FOR_SEQUENTIAL_KEY = OFF) ON [PRIMARY]
) ON [PRIMARY] TEXTIMAGE_ON [PRIMARY]
GO

EXEC sys.sp_addextendedproperty @name=N'MS_Description', @value=N'学生标识' , @level0type=N'SCHEMA',@level0name=N'dbo', @level1type=N'TABLE',@level1name=N'Student', @level2type=N'COLUMN',@level2name=N'StudentId'
GO

EXEC sys.sp_addextendedproperty @name=N'MS_Description', @value=N'姓名' , @level0type=N'SCHEMA',@level0name=N'dbo', @level1type=N'TABLE',@level1name=N'Student', @level2type=N'COLUMN',@level2name=N'Name'
GO

EXEC sys.sp_addextendedproperty @name=N'MS_Description', @value=N'性别' , @level0type=N'SCHEMA',@level0name=N'dbo', @level1type=N'TABLE',@level1name=N'Student', @level2type=N'COLUMN',@level2name=N'Gender'
GO

EXEC sys.sp_addextendedproperty @name=N'MS_Description', @value=N'年龄' , @level0type=N'SCHEMA',@level0name=N'dbo', @level1type=N'TABLE',@level1name=N'Student', @level2type=N'COLUMN',@level2name=N'Age'
GO

EXEC sys.sp_addextendedproperty @name=N'MS_Description', @value=N'出生日期' , @level0type=N'SCHEMA',@level0name=N'dbo', @level1type=N'TABLE',@level1name=N'Student', @level2type=N'COLUMN',@level2name=N'Birthday'
GO

EXEC sys.sp_addextendedproperty @name=N'MS_Description', @value=N'身份证' , @level0type=N'SCHEMA',@level0name=N'dbo', @level1type=N'TABLE',@level1name=N'Student', @level2type=N'COLUMN',@level2name=N'IdCard'
GO

EXEC sys.sp_addextendedproperty @name=N'MS_Description', @value=N'启用' , @level0type=N'SCHEMA',@level0name=N'dbo', @level1type=N'TABLE',@level1name=N'Student', @level2type=N'COLUMN',@level2name=N'Enabled'
GO

EXEC sys.sp_addextendedproperty @name=N'MS_Description', @value=N'创建时间' , @level0type=N'SCHEMA',@level0name=N'dbo', @level1type=N'TABLE',@level1name=N'Student', @level2type=N'COLUMN',@level2name=N'CreationTime'
GO

EXEC sys.sp_addextendedproperty @name=N'MS_Description', @value=N'创建人标识' , @level0type=N'SCHEMA',@level0name=N'dbo', @level1type=N'TABLE',@level1name=N'Student', @level2type=N'COLUMN',@level2name=N'CreatorId'
GO

EXEC sys.sp_addextendedproperty @name=N'MS_Description', @value=N'最后修改时间' , @level0type=N'SCHEMA',@level0name=N'dbo', @level1type=N'TABLE',@level1name=N'Student', @level2type=N'COLUMN',@level2name=N'LastModificationTime'
GO

EXEC sys.sp_addextendedproperty @name=N'MS_Description', @value=N'最后修改人标识' , @level0type=N'SCHEMA',@level0name=N'dbo', @level1type=N'TABLE',@level1name=N'Student', @level2type=N'COLUMN',@level2name=N'LastModifierId'
GO

EXEC sys.sp_addextendedproperty @name=N'MS_Description', @value=N'是否删除' , @level0type=N'SCHEMA',@level0name=N'dbo', @level1type=N'TABLE',@level1name=N'Student', @level2type=N'COLUMN',@level2name=N'IsDeleted'
GO

EXEC sys.sp_addextendedproperty @name=N'MS_Description', @value=N'版本号' , @level0type=N'SCHEMA',@level0name=N'dbo', @level1type=N'TABLE',@level1name=N'Student', @level2type=N'COLUMN',@level2name=N'Version'
GO

EXEC sys.sp_addextendedproperty @name=N'MS_Description', @value=N'扩展' , @level0type=N'SCHEMA',@level0name=N'dbo', @level1type=N'TABLE',@level1name=N'Student', @level2type=N'COLUMN',@level2name=N'ExtraProperties'
GO

EXEC sys.sp_addextendedproperty @name=N'MS_Description', @value=N'学生' , @level0type=N'SCHEMA',@level0name=N'dbo', @level1type=N'TABLE',@level1name=N'Student'
GO

点击执行按钮, Student 示例表创建完成.

创建 PostgreSql 代码生成数据库

如果你使用 PostgreSql 数据库,请按下面步骤创建 PostgreSql 示例数据库和示例表.

创建 Demo.Generator 数据库

打开 PostgreSql 客户端,新建数据库 Demo.Generator .

sql 复制代码

create database "Demo.Generator"
    with owner admin;

添加示例表 Student

运行下面Sql之前先切换到 Demo.Generator 数据库.

sql 复制代码

create table "Student"
(
    "StudentId"            uuid         not null
        constraint "PK_Student"
            primary key,
    "Name"                 varchar(200) not null,
    "Gender"               integer,
    "Age"                  integer,
    "Birthday"             timestamp with time zone,
    "IdCard"               varchar(50),
    "Enabled"              boolean      not null,
    "CreationTime"         timestamp with time zone,
    "CreatorId"            uuid,
    "LastModificationTime" timestamp with time zone,
    "LastModifierId"       uuid,
    "IsDeleted"            boolean      not null,
    "ExtraProperties"      text,
    "Version"              bytea
);

comment on table "Student" is '学生';

comment on column "Student"."StudentId" is '学生标识';

comment on column "Student"."Name" is '姓名';

comment on column "Student"."Gender" is '性别';

comment on column "Student"."Age" is '年龄';

comment on column "Student"."Birthday" is '出生日期';

comment on column "Student"."IdCard" is '身份证';

comment on column "Student"."Enabled" is '启用';

comment on column "Student"."CreationTime" is '创建时间';

comment on column "Student"."CreatorId" is '创建人标识';

comment on column "Student"."LastModificationTime" is '最后修改时间';

comment on column "Student"."LastModifierId" is '最后修改人标识';

comment on column "Student"."IsDeleted" is '是否删除';

comment on column "Student"."ExtraProperties" is '扩展属性';

comment on column "Student"."Version" is '版本号';

alter table "Student"
    owner to admin;

创建 MySql 代码生成数据库

如果你使用 MySql 数据库,请按下面步骤创建 MySql 示例数据库和示例表.

创建 Demo.Generator 数据库

打开 MySql 客户端,新建数据库 Demo.Generator .

sql 复制代码

create database `Demo.Generator`

添加示例表 Student

运行下面Sql之前先切换到 Demo.Generator 数据库.

sql 复制代码

create table Student
(
    StudentId            char(36) charset ascii not null comment '学生标识'
        primary key,
    Name                 varchar(200)           not null comment '姓名',
    Gender               int                    null comment '性别',
    Age                  int                    null comment '年龄',
    Birthday             datetime(6)            null comment '出生日期',
    IdCard               varchar(50)            null comment '身份证',
    Enabled              tinyint(1)             not null comment '启用',
    CreationTime         datetime(6)            null comment '创建时间',
    CreatorId            char(36) charset ascii null comment '创建人标识',
    LastModificationTime datetime(6)            null comment '最后修改时间',
    LastModifierId       char(36) charset ascii null comment '最后修改人标识',
    IsDeleted            tinyint(1)             not null comment '是否删除',
    ExtraProperties      longtext               null comment '扩展属性',
    Version              longblob               null comment '版本号'
)
    comment '学生';

Web Api开发入门

准备

下载Util应用框架配套代码生成项目,如果已下载,请拉取最新代码进行更新.

生成项目基架

打开Util代码生成项目解决方案 Util.Generator.sln .

将项目 Util.Generators.Console 设置为启动项目.

Util.Generators.Console是一个控制台程序,只需修改几个简单配置,即可开始生成代码.

打开 appsettings.json 配置文件.

使用 Sql Server 生成代码

本小节使用 Sql Server 代码生成数据库.

appsettings.json 配置文件默认使用 Sql Server 数据库,连接字符串已经配置,如果与你的数据库设置不同,请修改.

按 F5 键启动控制台.

生成完成.

生成位置由 OutputPath 配置项 D:\Output 指定.

打开D盘,进入Output目录,可以看到生成的 Demo 项目.

使用 PostgreSql 生成代码

本小节使用 PostgreSql 代码生成数据库.

修改 appsettings.json 配置文件.

DbType : PgSql , 这个配置项指定使用的代码生成数据库类型.

TargetDbType: PgSql, 这个配置项指定项目使用的数据库类型.

ConnectionString: Server=127.0.0.1;User Id=admin;Password=admin;Database=Demo.Generator ,指定连接字符串

修改 appsettings.json 配置文件后,需要重新生成项目,否则可能不生效.

重新生成 Util.Generators.Console 项目, 按 F5 键启动控制台.

生成完成.

生成位置由 OutputPath 配置项 D:\Output 指定.

打开D盘,进入Output目录,可以看到生成的 Demo 项目.

使用 MySql 生成代码

本小节使用 MySql 代码生成数据库.

修改 appsettings.json 配置文件.

DbType : MySql , 这个配置项指定使用的代码生成数据库类型.

TargetDbType: MySql, 这个配置项指定项目使用的数据库类型.

ConnectionString: Server=127.0.0.1;User Id=root;Password=admin;Database=Demo.Generator;Port=3306;Charset=utf8 ,指定连接字符串

修改 appsettings.json 配置文件后,需要重新生成项目,否则可能不生效.

重新生成 Util.Generators.Console 项目, 按 F5 键启动控制台.

生成完成.

生成位置由 OutputPath 配置项 D:\Output 指定.

打开D盘,进入Output目录,可以看到生成的 Demo 项目.

运行示例项目

打开示例项目解决方案 Demo.sln.

解决方案分层结构基于领域驱动设计(DDD)分层架构.

DDD分层架构包含大量构造块,对于大部分业务模块,手工编写这些构造块是枯燥而低效的,使用代码生成可以简化基础管道代码的编写.

如果你对DDD一无所知,可以把它们当成三层架构使用即可.

代码生成以机械的单表方式生成CRUD操作,如果你的业务较为复杂,在生成后立即修改它们.

你不应该依赖代码生成器,通常只在项目初期创建项目基架,后续变更仅生成代码片断并手工合并到你的项目,而不是完全覆盖.

查看代码生成质量

下面来看看生成的代码质量如何.

打开 Student 实体类.

每个实体,代码生成模板会创建两个文件,其中 .Base 结尾的文件用于放置属性,另一个放置业务方法.

对于简单的实体类,可能没有业务方法,你可以合并成一个文件.

可以看到生成的代码十分整洁,并已从必要的基类继承,还包含了注释和基础验证.

运行Web Api项目

打开 Demo.Api 项目下的 appsettings.Development 配置文件.

如果你的代码生成数据库以 .Generator结尾,会帮你创建默认的开发数据库连接字符串.

对于本示例项目,开发数据库名称默认为 Demo .

如果生成的连接字符串为空值,或需要修改参数,请自行配置连接字符串.

DefaultConnection 是Web Api项目的连接字符串, TestConnection 用于Web Api项目的集成测试.

按 F5 键启动 Demo.Api 项目.

Util 使用 Entity Framework Core 作为主要的数据访问框架.

Web Api项目已经配置了数据库迁移,不必手工输入命令行,启动时会自动运行命令.

可以看到 Demo.Data.SqlServer 项目已经创建 Migrations 迁移目录.

数据库也已经创建 Demo 数据库.

如果使用其它数据库生成代码,则与相应的数据库保持一致,比如 Demo.Data.MySql .

数据迁移完成,将打开 Swagger 页面.

下面我们使用 Swagger 调用 Web Api 创建一个学生.

找到 POST /api/Student , 点击 Try it out 按钮.

输入下列Json数据, 点击 Execute 按钮.

json 复制代码

{
  "name": "张三",
  "gender": 0,
  "age": 18,
  "birthday": "2023-10-19T06:53:55.469Z",
  "idCard": "123",
  "enabled": true
}

Swagger返回操作成功消息.

查询数据库 Student 表,可以看到已经插入成功.

运行其它数据库生成代码的操作类似.

后记

Web Api已经运行起来,但只能通过Swagger操作,下一篇我们将把基于Ng Zorro组件库的Angular UI运行起来.