背景:

上周,把 Taurus.MVC 在 Linux (CentOS7) 上部署任务完成后。

也不知怎么的,忽然就想给框架集成一下WebAPI文档功能,所以就动手了。

以为一天能搞完,结果,好几天过去了。

本来还想集成自动化批量执行测试功能,不过想想还是放到下一版本实现吧。

感觉差不多了,就先和大伙分享一下:

Taurus.MVC Nuget 更新:

昨夜,Nuget的Package升级了一下,和源码版本做了下同步。

通常源码的版本都会比Nuget包的靠前一个小版本:

目前:Taurus.MVC 升级到:V2.3.0.0 (CYQ.Data 同步升级到:V5.7.9.7)

最近版本的更新内容(好多功能都是在 CYQ.Data 里升级,所以这里记录很少):

V2.2.3.5(2017-04-19) - V 2.3 (2019-03-22)
1:支持Controller分布在不同的dll中(Taurus.Controllers配置允许多个,逗号分隔)。
2:支持Controller二次继承(A:B   B:Taurus.Core.Controller)

1:支持NetCore下的的部署(路径和大小写调整)

1、增加了CMS功能的标签替换功能。
2、增加参数验证属性(Require),验证是否必填写和正则格式。
3、增强了参数的类型转换。
4、增加WebAPI文档生成功能。
5、CYQ.Data同时升级到V5.7.9.7

下面介绍一下重点功能:

一、新增几个请求属性:HttpPut、HttpHead、HttpDelete

原来只有HttpGet和HttpPost。

所以方法只能指定其中的一个,如:

[HttpGet]
public void GetToken(string un, string pwd) { }

现在新增了几个,机制稍为调整了一下,还允许可以同时指定多个:

[HttpPost,HttpPut]
public void GetToken(string un, string pwd) { }

二、新增参数验证属性:Require

该属性参数有4个重载:

public RequireAttribute(string paraName)
public RequireAttribute(string paraName, bool isRequired, string regex)
public RequireAttribute(string paraName, bool isRequired, string regex, string outParaName)
public RequireAttribute(string paraName, bool isRequired, string regex, string emptyTip, string regexTip)

一共6种使用方法:

使用一:指定un参数不能为空。

[HttpGet,Require("un")]
public void GetToken(string un, string pwd) { }

使用二:指定un、pwd、random三个参数都不能为空,Require可以指定多个。

[HttpPost,Require("un,pwd"),Require("random")]
public void GetToken(string un, string pwd) { }

使用三:指定user实体内的UserName参数不能为空、para数组内第1个对象的Name参数不能为空。

[HttpPost,Require("user.UserName,para.0.Name"]
public void GetToken(Users user,List<ParaEntity> para) { }

使用四:指定un不能为空,同时满足手机号的正则验性规则。

[HttpGet,Require("un",true,RegexConst.Mobile)]
public void GetToken(string un, string pwd) { }

使用五:指定验证的提示文字。

[HttpGet,Require("un",true,RegexConst.Mobile,"用户名")]
public void GetToken(string un, string pwd) { }

PS说明:没指定提示文字前,默认的提示是:

{0} is required.

{0} is invalid.

指定提示文字后,如果是中文,则提示变为中文:

{0}不能为空。

{0}格式错误。

使用六:指定自定义提示文字。

[HttpGet,Require("un",true,RegexConst.Mobile,"手机号是不能为空的","国内的手机号是11位数字的。")]
public void GetToken(string un, string pwd) { }

三、增强功能的:CMS 标签语法

1、${xxx} 允许xxx指定从系统的请求参数中获取:

A:从Get的请求参数中获取;

B:从Request[XXX]的请求参数中获取;

C:从Request.Header的请求参数中获取。

示例:${host}是从系统变量中获取的。

                <h1 id="labSpaceName">
                    <a href="#">Web API 文档 - Taurus.MVC</a></h1>
                <h2 id="labSpaceIntro">Host:http://${host}</h2>

2、${xxx:这里可以设置默认值。} 允许指定参数无值时的默认值。

示例:/detail?d=

                            <h1 class="title_txt">
                                <a href="#">${d:这家伙很懒,没有写说明。}</a>
                            </h1>

四、默认实现的用户权限及Token机制

【PS:在新版本中,这个组件从核心组件中移除,做为单独的组件放在开源代码的 plugin 目录下】

如果要开启此功能,你需要设置以下的配置:

<!--是否启动默认的Token机制,可配置的映射字段:TableName,UserName,Password(这三个必填写,后面可选),FullName,Status,PasswordExpireTime,Email,Mobile,RoleID,TokenExpireTime(这个是配置小时)-->
    <add key="Taurus.Auth" value="{TableName:Users,TokenExpireTime:24}"/>

指定好表名,及其它字段名的映射之后,该功能就自动开启了。

如果其它字段名和系统默认的名称一样,则可以不用指定映射。

对于WebAPI,启用后,可以通过以下路径获取Token

/auth/gettoken
参数:
?uid=xxx&pwd=xxx

对于方法的验证,指定token属性即可

[Token]
public void GetXX() { }

另外提供了AuthHelper类,集成(MVC)下的注册、登陆、退出、获取用户信息等基础功能。

public static bool Login(string userName, string password, out string errMsg)
public static bool Reg(string userName, string password, out string msg)
public static void Logout()
public static bool ChangePassword(string password)

基础属性:
public static bool TokenIsValid
public static string UserID
public static string UserName
public static string FullName
public static string Token

五、WebAPI文档生成功能

【PS:新版本,本功能无需要配置,在运行会检测:存在Views目录(或.NET Core 下存在webroot\\Views 目录),会自动解压管理后台和Doc目录,并默认启用】。

其实这个才是重点,上面的功能,都是在弄这个的时候,顺带完成的。

只需要配置:

 <!--是否启动创建API文档,访问路径为:/doc-->
    <add key="Taurus.IsStartDoc" value="true"/>

然后访问:/doc 路径,就可以看到WebAPI文档了。

示例地址:http://taurus.cyqdata.com/doc

对于控制器,项目属性里需要勾选输出Xml文档选项:

 

文档的默认界面(找皮肤好辛苦,最后找了秋色的博客皮肤改的)

方法详情页面:

 

如果要调整样式,可以看(如果是引用的Nuget,你目前仍需要从框架开源的源码处把Doc目录的Copy过去,后续版本会把这个打包进dll,动态解压):

 

总结:

1、Taurus.MVC 是轻量级的 mvc 框架,真正意义上的前后端分离,没有后端语法入侵。

2、学习成本比 ASP.NET MVC 低很多,性能高,易掌控,支持大并发。

3、同一套代码,一套机制,可以走在Win和Linux中,不用搞个.NET Core还部署在window这么尴尬。

4、回归Http本质的框架,你才能以不变应万变,不用陷入不断变化的框架的无限深坑里。

开源地址:https://github.com/cyq1162/Taurus.MVC

 

posted on 2019-03-22 17:57  路过秋天  阅读(1816)  评论(3编辑  收藏  举报
路过秋天