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 等資料建模工具生成.
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 .
create database "Demo.Generator"
with owner admin;
新增範例表 Student
執行下面Sql之前先切換到 Demo.Generator 資料庫.
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 .
create database `Demo.Generator`
新增範例表 Student
執行下面Sql之前先切換到 Demo.Generator 資料庫.
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 按鈕.
{
"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執行起來.
