为开发人员，我们依赖于静态分析工具来检查、lint(分析)和转换我们的代码。我们使用这些工具来帮助我们提高生产效率并生成更好的代码。然而，当我们使用markdown编写内容时，可用的工具就很少。

在本文中，我们将介绍如何开发一个Markdown扩展来解决在使用Markdown管理Django站点中的内容时遇到的挑战。

你认为他们有linter吗？

照片来自Pexels,由mali maeder拍摄

问题

像每个网站一样，我们在主页、FAQ部分和“关于”页面等地方都有不同类型的(大部分)静态内容。很长一段时间以来，我们都是在Django模板中直接管理这些内容的。

当我们最终决定是时候将这些内容从模板转移到数据库中时，我们认为最好使用Markdown。从Markdown生成HTML更安全，它提供了一定程度的控制和一致性，并且对于非技术用户来说更容易处理。随着我们转移过程的进展，我们注意到我们遗漏了一些东西:

内部链接

当URL更改时，链接到内部页面的链接可能会中断。在Django模板和视图中，我们使用了reverseand {% url %}，但是这在普通的Markdown中是不可用的。

在不同环境之间进行复制

绝对内部连接不能在不同环境之间进行复制。这可以使用相对链接来解决，不过目前没有开箱即用的增强这一点的方法。

无效链接

无效链接会损害用户体验，并导致用户质疑整个内容的可靠性。这并不是Markdown独有的东西，只不过HTML模板是由对URL有一定了解的开发人员维护的。另一方面，Markdown文档是为非技术写作人员设计的。

前期工作

当我研究这个问题时，我搜索了Python linters、Markdown预处理器和扩展来帮助生成更好的Markdown。结果都不是很好。一个引人注目的方法是使用Django模板来生成Markdown文档。

使用Django模板预处理Markdown

使用Django模板，你可以使用诸如url之类的模板标记来反向查询URL名称，并配合使用条件、变量、日期格式和所有其他Django模板特性。这种方法本质上是使用Django模板作为Markdown文档的预处理程序。

我个人认为这可能不是非技术作家的最佳解决方案。另外，我担心提供对Django模板标记的访问可能是危险的。

使用 Markdown

对这个问题有了更好的理解之后，我们准备在Python中更深入地研究Markdown。

将Markdown转换为HTML

要在Python中开始使用Markdown，我们先安装markdown包：

接着，创建一个Markdown对象并使用其函数将一些Markdown转换成HTML：

你现在可以在你的模板中使用这个HTML代码片段。

使用Markdown扩展

基本的Markdown处理器提供了生成HTML内容的基本要素。对于更“新奇”的选项，Python markdown包包含了一些内置扩展。一个流行的扩展是“extra”扩展，除了其他东西之外，它增加了对隔离代码块的支持:

为了使用我们独特的Django功能扩展Markdown，我们将开发自己的扩展。

创建一个Markdown扩展来处理内联链接

如果你查看源代码，你将看到要将markdown转换为HTML, Markdown会使用多种不同的处理器。一种类型的处理器是内联处理器。内联处理器会匹配特定的内联模式，如链接、反引号、粗体文本和带下划线的文本，并将它们转换为HTML。

我们的Markdown扩展的主要目的是验证和转换链接。因此，我们最感兴趣的内联处理器是LinkInlineProcessor。这个处理器以[Haki的网站](https://hakibenito.com)的形式获取markdown ，解析它并返回一个包含链接和文本的元组。

为了扩展该功能，我们扩展了LinkInlineProcessor并创建了一个Markdown.Extension, 我们用它来处理链接:

我们来将这段代码分解一下：:

• DjangoUrlExtension扩展注册了一个名为DjangoLinkInlineProcessor的内联链接处理器。这个处理器将取代任何其他现有的链接处理器。

• 内联处理器DjangoLinkInlineProcessor扩展了内置的LinkInlineProcessor，并在它处理的每个链接上调用clean_link函数。

• clean_link函数接收一个链接和一个域名，并返回一个转换后的链接。这就是我们要插入我们的实现的地方。

如何获得网站域名

要识别到你自己网站的链接，你必须知道你的网站的域名。如果你正在使用Django的sites框架，那么你可以使用它来获取当前域名。

我没有把它包含在我的实现中，因为我们没有使用sites框架。相反，我们在Django设置中设置了一个变量。

获取当前域名的另一种方法是使用HttpRequest对象。如果内容只在你自己的站点中被编辑，你可以尝试从请求对象中插入站点域名。这可能需要对你的实现进行一些更改。

要使用该扩展，请在初始化一个新的Markdown实例时添加它:

太好了，这个扩展已经被使用了，我们准备进入有趣的部分了！

验证和转换Django链接

既然我们得到了在所有链接上调用clean_link的扩展，那我们可以来实现我们的验证和转换逻辑。

验证mailto链接

要开始工作，我们将从一个简单的验证开始。mailto链接对于使用预定义的收件人地址、主题甚至消息正文打开用户的电子邮件客户端非常有用。

一个常见的mailto链接是这样的:

这个链接将打开你的电子邮件客户端，并设置成撰写一封主题行为“我需要帮助!”的新电子邮件给“support@service.com”。

mailto链接不一定非要包含电子邮件地址。如果你看一看这篇文章底部的“分享”按钮，你会发现像这样的一个mailto链接:

这个mailto链接没有包含收件人，仅包含了主题行和消息正文。

既然我们已经很好地理解了mailto链接是什么样子的，我们就可以向clean_link函数添加第一个验证:

为了验证mailto链接，我们向clean_link中添加了以下代码:

• 检查链接是否以mailto:开头，以识别相关链接。

• 使用正则表达式将链接分割到它的组件。

• 从mailto链接中删除实际的电子邮件地址，并使用Django的EmailValidator验证它。

注意，我们还添加了一种名为InvalidMarkdown的新异常类型。我们定义了自己的自定义异常类型，以将它与markdown本身所引发的其他错误区分开来。

自定义错误类

我曾经写过关于自定义错误类的文章，为什么它们是有用的，以及你什么时候应该使用它们。

在我们继续之前，让我们添加一些测试，看看它的实际效果:

太棒了！按预期的运行了。

处理内部和外部链接

既然我们已经了解了mailto链接，我们也可以处理其他类型的链接:

外部链接

• 我们的Django应用程序外部的链接。

• 必须包含一个页面跳转协议（scheme）:http或https。

• 理想情况下，我们还希望确保这些链接没有被破坏，但我们现在不会这样做。

内部链接

• 到我们的Django应用程序中的页面的链接。

• 链接必须是相对的:这将允许我们在不同环境之间移动内容。

• 使用Django的URL名称而不是一个URL路径:这将允许我们安全地来回移动视图，而不必担心markdown内容中的失效链接。

• 链接可能包含查询参数(?)和片段(#)。

SEO

从SEO的角度来看，公共URL不应该改变。当他们这样做的时候，你应该使用重定向正确地处理它，否则你可能会受到搜索引擎的惩罚。

有了这个需求列表，我们就可以开始工作了。

解析URL名称

要链接到内部页面，我们希望编写者提供一个URL名称，而不是URL路径。例如，假设我们有这个视图:

这个页面的URL路径是https://example.com/， URL名称是home。我们想要在我们的markdown链接中使用这个URL名称home，就像这样:

这将渲染到:

我们还想支持查询参数和散列：

这将渲染到以下HTML：

在使用URL名称时，如果我们更改了URL路径，内容中的链接将不会被破坏。要检查作者提供的href是否是一个有效的url_name，我们可以尝试reverse它:

URL名称“home”指向URL路径“/”。当没有匹配项时，将会引发一个异常:

在我们继续之前，当URL名称包含查询参数或散列时，会发生什么:

这是有意义的，因为查询参数和散列不是URL名称的一部分。

要使用reverse并支持查询参数和散列，我们首先需要清除值。然后，检查它是一个有效的URL名称，并返回包含查询参数和散列的URL路径，如果提供了的话:

这个代码段使用一个正则表达式来以？或#的出现对href进行分割，并返回各部分。

请确保它可以工作:

太了不起了!作者们现在可以在Markdown中使用URL名称了。它们还可以包括要添加到该URL的查询参数和片段。

处理外部链接

要正确处理外部链接，我们需要检查两件事:

1.外部链接总是提供一个跳转协议，http:或者https:。

2.阻止到我们自己网站的绝对链接。内部链接应该使用URL名称。

到目前为止，我们已经处理了URL名称和mailto链接。如果我们通过了这两个检查，这意味着href是一个URL。让我们从检查链接是否是链接到我们自己的网站开始:

函数urlparse会返回一个命名元组，该元组包含URL的不同部分。如果netloc属性等于site_domain，那么该链接就确实是一个内部链接。

如果URL实际上是内部的，我们就需要终止。但是，请记住，作者们不一定是技术人员，因此我们希望帮助他们，并提供一个有用的错误消息。我们要求该内部链接使用URL名称而不是URL路径，所以最好让作者们知道他们提供的路径的URL名称。

要获得一个URL路径的URL名称，Django为我们提供了一个名为resolve的函数:

当找到匹配项时，resolve会返回一个ResolverMatch对象，其中包含URL名称和其他信息。当没有找到匹配项时，它就会引发一个错误:

这实际上就是Django在底层所做的工作，用来确定在一个新请求到来时执行哪个视图函数。

为了给作者们提供更好的错误信息，我们可以使用来自ResolverMatch对象的URL名称:

当我们识别出内部链接时，我们要处理两种情况:

• 我们没有识别出这个URL:这个URL很可能是不正确的。请作者检查该URL是否有错误。

• 我们识别出了这个URL: 这个URL是正确的，所以就告诉作者应该使用什么URL名称。

我们来实际地看一下它:

漂亮!外部链接被接受，内部链接被拒绝，并带有一个有用的消息。

要求跳转协议

我们要做的最后一件事是确保外部链接包含一个跳转协议，要么是http:，要么是https:。让我们将这最后一部分添加到函数clean_link:

使用解析后的URL，我们可以很容易地检查跳转协议。让我们确保它正在工作:

我们向这个函数提供了一个没有跳转协议的链接，但是它运行失败了，并显示了一条有用的消息。太酷了!

整合代码

这是clean_link函数的全部代码：

要了解所有这些特性的一个实际用例是什么样子的，请看下面的内容:

这将产生以下HTML:

不错!

结论

我们现在有一个很不错的扩展，它可以验证和转换Markdown文档中的链接!现在，在不同环境之间移动文档和保持内容整洁要容易多了，最重要的是，可以保持正确和最新!

源码

你可以在这个gist中找到全部源代码。（地址：https://gist.github.com/hakib/73fccc340e855bb65f42197e298c0c7d ）

题外话

本文中所描述的功能对我们很有用，但是你可能需要根据自己的需求对它进行调整。

如果你需要一些想法，那么除了这个扩展之外，我们还创建了一个markdown Preprocessor，它允许作者们在markdown中使用常量。例如，我们定义了一个名为SUPPORT_EMAIL的常量，我们像这样使用它:

该预处理程序将用我们定义的文本替换字符串$SUPPORT_EMAIL，然后才渲染Markdown。

英文原文：https://hakibenita.com/django-markdown
译者：Nothing

ttpServer 静态下载

先来看一段代码，启动一个静态的http服务

import CBHttp.code

function main(parm)
{
    var httpServer = new HttpServer();
    httpServer.startServer();
	
    while(1)  //主线程不能退出
    {
        Sleep(1000);
    }
}

服务启动好了，假设我们的项目根目录是E:\cbrotherwork\httpserver，那么我们的服务根路径就默认是E:\cbrotherwork\httpserver\webroot

我们新建txt文件E:\cbrotherwork\httpserver\webroot1.txt，在文本里输入内容Hello HttpServer!。

然后我们打开本机浏览器输入：http://127.0.0.1:8000/111.txt，你发现你在网页上访问到了111.txt

主流的文件格式都支持下载

MIME控制

静态下载的过程中，有时需要控制可下载的文件格式，那么就要手动调配MIME

import CBHttp.code

function main(parm)
{
    var httpServer = new HttpServer();
	
    httpServer.addMIME("mystyle","text/html");  //添加后缀名为.mystyle,mime为text/html
    httpServer.addMIME("c");  			//添加后缀名为.c，mime类型让系统自动识别
    httpServer.removeMIME("gif");  		//删除gif
	
    var mimiemap = httpServer.getMIME();  	//获取目前支持的mime类型
	
    mimiemap.begin();
    do
    {
        print mimiemap.getKey() + ":" + mimiemap.getValue();
    }
    while(mimiemap.next());		
	
    httpServer.startServer();
	
    while(1)
    {
        Sleep(1000);
    }
}

运行结果：

rar:application/octet-stream
bmp:image/bmp
xml:application/xml
html:text/html
c:text/plain
js:application/x-javascript
txt:text/plain
ico:image/x-icon
zip:application/zip
jpg:image/jpeg
mystyle:text/html
7z:application/octet-stream
json:application/json
swf:application/x-shockwave-flash
css:text/css
png:image/png

HttpServer 动态接口

我们通常需要在用户调用一个接口时通过一些条件来返回不同的内容，下面我们再通过一段代码看一下

import CBHttp.code

class HelloAction
{
    function DoAction(request,respon)				//这个函数写法是固定的，request表示客户端请求信息，respon是回复给客户机的信息
    {
        var myTime = new Time();
        respon.write("now time is:" + myTime.strftime("%Y/%m/%d %H:%M:%S"));
        respon.flush();
    }	
}

function main(parm)
{
    var httpServer = new HttpServer();
    httpServer.addAction("hello.cb",new HelloAction());		//我们注册接口hello.cb，响应类是HelloAction
    httpServer.startServer();
	
    while(1)	//主线程不能退出
    {
        Sleep(1000);
    }
}

然后我们浏览器输入：http://127.0.0.1:8000/hello.cb,每次访问返回的都是当前时间。

接口名字可以是任意字符串，官方建议用统一的后缀，方便跟其他web服务器协作。

HttpServer 接口

除了stopServer，其他接口都应该在startServer之前调用。

HttpServer 响应Action类

响应类必须要有function DoAction(request,respon)函数，如果没有会注册失败。

这个方法会被多线程调用，如果要访问公共资源需要加锁。

·request记录了客户端请求的信息

·respon是返回给客户端的信息

Cookie 类

在日常开发中，服务器需要通过cookie来判别客户机身份，CBrother提供了Cookie类来描述http头中的Set-Cookie与Cookie字段

其中带密码的setValue方法会用密码和原始明文算一个md5值作为cookie签名，这样保证了cookie不可被伪造，一般可以用于登陆状态验证。当然，在一些安全性要求比较高的场景，开发者也可以自己实现安全级别更高的cookie加密验证方式。

通过一个段代码来学习一下Cookie的用法:

class CookieAction
{
    function DoAction(request,respon)
    {
        var cookieCnt = request.getCookieCount();  //获取客户机Cookie数量
        if(cookieCnt > 0)
        {
            for(var i = 0 ; i < cookieCnt ; i++)  //遍历的方式可以获取所有的Cookie，包括名字相同的Cookie
            {
                //客户机已经有cookie
                var cookie = request.getCookie(i);
                if(cookie.getName() == "pwdCookie")
                {
                    print cookie.getValue();
                    print cookie.getValue("pwd222");  //带密码的cookie
                }
                else
                {
                    print cookie.getValue();  //明文cookie
                }
            }
			
            var pwdCookie request.getCookie("pwdCookie");  //根据名字获取Cookie，如果有同名Cookie则只返回第一个
            print pwdCookie.getValue("pwd222");			
        }
        else
        {
            //客户机没有cookie
            var cookie = new Cookie("normalCookie","3333");
            respon.addCookie(cookie);  //添加明文cookie
			
            cookie = new Cookie();
            cookie.setName("pwdCookie");
            cookie.setValue("3333","pwd222");
            respon.addCookie(cookie);  //添加带密码的cookie
        }
		
        var myTime = new Time();
        respon.write("now time is:" + myTime.strftime("%Y/%m/%d %H:%M:%S"));
        respon.flush();
    }	
}

表单FormData 类

CBrother提供了FormData类来描述form表单数据

比如web前端提交的form表单结构如下：

<form method="post" action="form.cb" >
	<input type="text" name="txt1">
	<input type="text" name="txt2">
	<input type="password" name="userpass"
	<input type="radio" name="sex" value="man" checked>man
	<input type="radio" name="sex" value="woman">woman
	<input type="file" name="file" value="hiddenvalue" multiple="multiple"/>
	<input type="submit" value="提交(提交按钮)">
</form>

网页展示效果如下：

因为这个表单没有指定enctype，所以Content-Type为application/x-www-form-urlencoded，我们日常使用到的大部分表单都是这种格式。当前端post提交后服务器使用如下方式获取表单数据

class FormAction
{
    function DoAction(request,respon)
    {
        print request.getData();  //打印发送的数据
        print "**********************分割线*******************************";
        
        var formdata = request.getFormData();
        if(formdata == null)
        {
            return;	//只有Content-Type为application/x-www-form-urlencoded或者multipart/form-data时候才会返回FormData对象，否则返回null
        }
		
        var type = formdata.getType();
        if(type == FORM_WWW_URLENCODED)	//Content-Type为application/x-www-form-urlencoded类型的表单
        {
            var textCnt = formdata.getTextCnt();
            for(var i = 0 ; i < textCnt ; i++)
            {
                print formdata.getTextName(i) + ":" + formdata.getText(i);
            }
        }
    }	
}

服务器输出结果：

txt1=111&txt2=222&userpass=333&sex=man&file=111.txt
**********************分割线*******************************
txt1:111
txt2:222
userpass:333
sex:man
file:111.txt

Multipart 类

这里需要学习一下form添加enctype=multipart/form-data时提交的报文格式

Multipart类来描述form表单在multipart/form-data数据类型下的一个input数据，这个类型的表单一般用在上传文件

比如web前端提交的form表单结构如下：(只是添加了一个enctype="multipart/form-data")

<form method="post" action="form.cb"  enctype="multipart/form-data">
	<input type="text" name="txt1">
	<input type="text" name="txt2">
	<input type="password" name="userpass"
	<input type="radio" name="sex" value="man" checked>man
	<input type="radio" name="sex" value="woman">woman
	<input type="file" name="file" value="hiddenvalue" multiple="multiple"/>
	<input type="submit" value="提交(提交按钮)">
</form>

网页展示效果没有变化如下：

添加了enctype，Content-Type变成multipart/form-data，服务器使用如下方式获取表单数据

class FormAction
{
    function DoAction(request,respon)
    {
        print request.getData();  //打印发送的数据
        print "**********************分割线*******************************";
        
        var formdata = request.getFormData();
        if(formdata == null)
        {
            return;	//只有Content-Type为application/x-www-form-urlencoded或者multipart/form-data时候才会返回FormData对象，否则返回null
        }
		
        var type = formdata.getType();
        if(type == FORM_MULTI_PART)	//Content-Type为multipart/form-data类型的表单
        {
            var formcnt = formdata.getMultiPartCnt();
            for(var i = 0 ; i < formcnt ; i++)
            {
                var muldata = formdata.getMultiPart(i);				
                if(muldata.isFile())  //如果是上传的文件
                {
                    for(var j = 0 ; j < muldata.getFileCount() ; j++)
                    {
                        //上传的文件可以在这里通过File对象把数据保存到文件里，CBrother目录下sample/http/httpserver_form.cb里面有例子，这里只是把数据打印出来
                        var filedata = muldata.getFile(j);
                        print filedata.getParm("name") + " " + filedata.getParm("filename") + ": size=" + filedata.getDataLen() + " value=" + filedata.getData();
                    }
                }
                else
                {
                    print muldata.getParm("name") + ":" + muldata.getData();
                }
            }
        }
    }	
}

服务器运行结果如下:

------WebKitFormBoundaryw7KfcBx8f23zh8d4
Content-Disposition: form-data; name="txt1"

111
------WebKitFormBoundaryw7KfcBx8f23zh8d4
Content-Disposition: form-data; name="txt2"

222
------WebKitFormBoundaryw7KfcBx8f23zh8d4
Content-Disposition: form-data; name="userpass"


------WebKitFormBoundaryw7KfcBx8f23zh8d4
Content-Disposition: form-data; name="sex"

man
------WebKitFormBoundaryw7KfcBx8f23zh8d4
Content-Disposition: form-data; name="file"; filename="111.txt"
Content-Type: text/plain

i'am 111.txt file value!
------WebKitFormBoundaryw7KfcBx8f23zh8d4--
**********************分割线*******************************
txt1:111
txt2:222
userpass:
sex:man
file 111.txt: size=24 value=i'am 111.txt file value!

HttpClientRequest 主动发起请求

在开发过程中，我们经常会遇到与第三方服务器通信，这时候就需要主动请求第三方服务器接口，CBrother提供了HttpClientRequest来主动访问别人提供的http和https接口

var myReq = new HttpClientRequest();

HttpClientResponse为主动请求后返回的结果，HttpClientRequest的flush方法会返回一个HttpClientResponse对象

var myReq = new HttpClientRequest();
myReq.setMethod("GET");
myReq.setUrl("https://www.baidu.com");
var myResponse = myReq.flush();

例子:

import CBHttp.code

function main(parm)
{
    var myReq = new HttpClientRequest();
    myReq.setMethod("GET");
    myReq.setUrl("https://www.baidu.com");
    var myRes = myReq.flush();
    print myRes.getStatus();
    print myRes.getData();
}

结果:

200
<html>
<head>
        <script>
                location.replace(location.href.replace("https://","http://"));
        </script>
</head>
<body>
        <noscript><meta http-equiv="refresh" content="0;url=http://www.baidu.com/"></noscript>
</body>
</html>

在开发过程中，为了降低服务器压力，经常需要用到keepalive来保持连接多次请求，看下面的例子:

import CBHttp.code
import lib/httpdef

function main(parm)
{
    var myReq = new HttpClientRequest();
    myReq.setMethod(HTTP_GET);
    myReq.setUrl("http://www.cbrother.net");
    myReq.setKeepAlive(true);		//开启keepalive，如果没有这一句默认是请求完毕后自动关闭连接
    var myRes = myReq.flush();
    print myRes.getStatus();
    print myRes.getData();
	
    myReq.reset();		//重置请求对象，仅保留网络连接，如果因为超时连接被服务器主动关闭，那么第二次请求会重新创建连接
	
    myReq.setMethod(HTTP_GET);
    myReq.setUrl("http://www.cbrother.net/doc.html");
    var myRes = myReq.flush();			//第二次请求没有开启keepalive，所以这句执行完后连接就会关闭了
    print myRes.getStatus();
    print myRes.getData();		
}

客户端使用Cookie例子:

function main(parm)
{
    var myReq = new HttpClientRequest();
    myReq.setMethod("GET");
    myReq.setUrl("https://www.baidu.com");
    myReq.addCookie(new Cookie("aaa","bbb"));  //本次请求添加cookie
    var myRes = myReq.flush();
	
    var cookieCnt = myRes.getCookieCount();  //服务器返回的cookie信息
    for(var i = 0 ; i < cookieCnt ; i++)
    {
        var cookie = request.getCookie(i);
		
        print cookie.getName();
        print cookie.getValue();
    }
}

客户端模拟form表单的例子:

import lib/httpdef

function main(parm)
{
    var clientReq = new HttpClientRequest();
    clientReq.setMethod(HTTP_POST);
    clientReq.setUrl("http://127.0.0.1:8003/form.cb");
    var formdata = clientReq.addFormData(FORM_MULTI_PART); //也可以用FORM_WWW_URLENCODED，FORM_WWW_URLENCODED类型不支持上传文件
    formdata.addText("111","111");
    formdata.addText("222","222");
    formdata.addFile("file","111.txt","222");
    formdata.addFile("file","222.txt","34567");
    clientReq.flush();	
}

HttpServer同一个端口支持多个不同内容的网站

如果需要在一台服务上同时布置多个网站，则需要在调用HttpServer下面几个接口时第二个参数传入网站的域名即可