Verne in GitHub

在 Spring Boot 中使用 Swagger

在使用 Spring Boot 构建一套 RESTful 接口的时候经常需要手工维护一份接口文档以提供给不同的客户端使用，有的时候手工维护成本太高，今天发现了一套自动化生成 RESTful 接口文档的工具 Swagger 。

Swagger 能根据 Spring Controller 接口自动生成一个文档页面，在代码中使用注解将接口文档注释，非常方便。 Swagger 整合到 Spring boot 项目中也非常方便。

添加依赖

在 pom.xml 中添加

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

最新的版本可以在 mvnrepository 上查到，或者上官网或者 github。

添加配置类

在项目 package 根下新建如下 Class:

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket helloApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("info.einverne.springboot.demo"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 文档标题
                .title("API 文档")
                // 文档描述
                .description("https://github.com/einverne/thrift-swift-demo/tree/master/spring-boot-demo")
                .termsOfServiceUrl("https://github.com/einverne/thrift-swift-demo/tree/master/spring-boot-demo")
                .version("v1")
                .build();
    }
}

通过@Configuration注解，让 Spring 来加载该类配置。再通过@EnableSwagger2注解来启用 Swagger2。

  • apiInfo() 用来创建 API 的基本信息，展现在文档页面中。
  • select() 函数返回一个 ApiSelectorBuilder 实例用来控制哪些接口暴露给 Swagger ，这里使用定义扫描包路径来定义， Swagger 会扫描包下所有 Controller 的定义并产生文档内容，除了被 @ApiIgnore 注解的接口。

添加接口注释

@ApiOperation 注解来给 API 增加说明、通过 @ApiImplicitParams、@ApiImplicitParam 注解来给参数增加说明。

一个简单的注释

@ApiOperation(value = "创建用户", notes = "根据 User 对象创建用户")
@ApiImplicitParam(name = "user", value = "用户详细实体 user", required = true, dataType = "User")
@RequestMapping(value = "", method = RequestMethod.POST)
public String postUser(@RequestBody User user) {
    users.put(user.getId(), user);
    return "success";
}

详细的例子可以参考源代码 https://github.com/einverne/thrift-swift-demo

再添加注释后启动 Spring boot, 访问 http://localhost:8080/swagger-ui.html 即可看到 API 文档

Api 注解

@Api 注解用于类上，说明类作用

  • value url
  • description
  • tags 设置该值，value 会被覆盖
  • basePath 基本路劲不可配置
  • position
  • produces “application/json”
  • consumes “application/json”
  • protocols http, https, wss
  • authorizations 认证
  • hidden 是否在文档隐藏

ApiOperation 注解

标记在方法上，对一个操作或 HTTP 方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的 HTTP 请求方法及路径组合构成一个唯一操作。此注解的属性有：

  • value 对操作的简单说明，长度为 120 个字母，60 个汉字。
  • notes 对操作的详细说明。
  • httpMethod HTTP 请求的动作名，可选值有：”GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”。
  • code 默认为 200，有效值必须符合标准的 HTTP Status Code Definitions

ApiImplicitParams

注解 ApiImplicitParam 的容器类，以数组方式存储。

ApiImplicitParam

对 API 的单一参数进行注解。虽然注解 @ApiParam 同 JAX-RS 参数相绑定，但这个 @ApiImplicitParam 注解可以以统一的方式定义参数列表，也是在 Servelet 及非 JAX-RS 环境下，唯一的方式参数定义方式。注意这个注解 @ApiImplicitParam 必须被包含在注解 @ApiImplicitParams 之内。可以设置以下重要参数属性：

  • name 参数名称
  • value 参数的简短描述
  • required 是否为必传参数
  • dataType 参数类型，可以为类名，也可以为基本类型（String，int、boolean 等）
  • paramType 参数的传入（请求）类型，可选的值有 path, query, body, header or form。

@RequestBody 这样的场景请求参数无法使用 @ApiImplicitParam 注解进行描述

ApiParam

增加对参数的元信息说明。这个注解只能被使用在 JAX-RS 1.x/2.x 的综合环境下。其主要的属性有：

  • required 是否为必传参数
  • value 参数简短说明

ApiModel

提供对 Swagger model 额外信息的描述。在标注 @ApiOperation 注解的操作内，所有的类将自动被内省（introspected），但利用这个注解可以做一些更加详细的 model 结构说明。主要属性有：

  • value model 的别名，默认为类名
  • description model 的详细描述

ApiModelProperty

对 model 属性的注解，主要的属性值有：

  • value 属性简短描述
  • example 属性的示例值
  • required 是否为必须值
  • hidden 隐藏该属性

ApiResponse

响应配置

  • code http 状态码
  • message 描述

ApiResponses

多个 Response

验证机制

考虑到安全的问题，每次请求 API 需要对用户进行验证与授权。目前主流的验证方式采用请求头部（request header）传递 token，即用户登录之后获取一个 token，然后每次都使用这个 token 去请求 API。如果想利用 swagger-UI 进行 API 测试，必须显式为每个需要验证的 API 指定 token 参数。这时可以为每个操作添加一个注解 @ApiImplicitParams，具体代码如下：

@ApiImplicitParams({@ApiImplicitParam(name = "TOKEN", value = "Authorization token", required = true, dataType = "string", paramType = "header")})

根据环境选择开启 Swagger

Swagger 提供了 enable 方法，可以通过设置该方法来选择开启 Swagger 来在线上环境禁用 Swagger。

@Bean
public Docket customImplementation(){
    return new Docket(SWAGGER_2)
        .apiInfo(apiInfo())
        .enable(environmentSpeficicBooleanFlag) //<--- Flag to enable or disable possibly loaded using a property file
        .includePatterns(".*pet.*");
}

如果使用 Spring @Profile 也可以

@Bean
@Profile("production")
public Docket customImplementation(){
    return new Docket(SWAGGER_2)
        .apiInfo(apiInfo())
        .enable(false) //<--- Flag set to false in the production profile
        .includePatterns(".*pet.*");
}

From: https://stackoverflow.com/a/27976261/1820217

reference


2017-10-16 Spring , Swagger , Java

每天学习一个命令： Linux 查看磁盘信息命令 di

平时在 Linux 上查看磁盘信息都使用 df -lh , -l 显示本地文件系统， -h 来表示 human readable 。虽然 df 在一定程度上能够满足查询磁盘剩余空间的需求，但是这里要介绍一款强大于 df 的命令 —- di 。

使用如下命令安装

sudo apt install di

di 命令是 disk information 的缩写，直接运行 di 会有如下结果

di
Filesystem         Mount               Size     Used    Avail %Used  fs Type
/dev/sda1          /                 901.2G   188.3G   667.1G   26%  ext4   
tmpfs              /dev/shm            7.8G     0.1G     7.6G    2%  tmpfs  
tmpfs              /run                1.6G     0.1G     1.5G    4%  tmpfs  
cgmfs              /run/cgmanager/     0.1M     0.0M     0.1M    0%  tmpfs  
tmpfs              /run/lock           5.0M     0.0M     5.0M    0%  tmpfs  
tmpfs              /run/user/0         1.6G     0.0G     1.6G    0%  tmpfs  
tmpfs              /run/user/1000      1.6G     0.0G     1.6G    0%  tmpfs  
tmpfs              /sys/fs/cgroup      7.8G     0.0G     7.8G    0%  tmpfs  
/dev/sda1          /var/lib/docker   901.2G   188.3G   667.1G   26%  ext4

di 默认的输出就是比较人性化的了。

看 di 的使用介绍 man di 就会发现 di 是这么介绍自己的

> di Displays usage information on mounted filesystems.  Block values are reported in a human readable format.  If the user or group has  a  disk  quota,  the  values  reported  are adjusted according the quotas that apply to the user.

一些简单的使用

A 选项打印所有挂载设备

di -A
Mount                fs Type Filesystem 
	Options                                                           
	    Size     Used     Free %Used  %Free 
	    Size     Used    Avail %Used  %Free 
	    Size     Used    Avail %Used  
	   Inodes     IUsed     IFree %IUsed
/                    ext4    /dev/sda1  
	rw,relatime,errors=remount-ro,data=ordered                        
	  901.2G   188.3G   712.9G   21%    79%  
	  901.2G   234.1G   667.1G   26%    74%  
	  855.4G   188.3G   667.1G   22%  
	 60014592   1372538  58642054    2% 
/dev/shm             tmpfs   tmpfs      
	rw,nosuid,nodev                                                   
	    7.8G     0.1G     7.6G    2%    98%  
	    7.8G     0.1G     7.6G    2%    98%  
	    7.8G     0.1G     7.6G    2%  
	  2036725       741   2035984    0% 
/run                 tmpfs   tmpfs      
	rw,nosuid,noexec,relatime,size=1629380k,mode=755                  
	    1.6G     0.1G     1.5G    4%    96%  
	    1.6G     0.1G     1.5G    4%    96%  
	    1.6G     0.1G     1.5G    4%  
	  2036725       777   2035948    0% 
/run/cgmanager/fs    tmpfs   cgmfs      
	rw,relatime,size=100k,mode=755                                    
	    0.1M     0.0M     0.1M    0%   100%  
	    0.1M     0.0M     0.1M    0%   100%  
	    0.1M     0.0M     0.1M    0%  
	  2036725        14   2036711    0% 
/run/lock            tmpfs   tmpfs      
	rw,nosuid,nodev,noexec,relatime,size=5120k                        
	    5.0M     0.0M     5.0M    0%   100%  
	    5.0M     0.0M     5.0M    0%   100%  
	    5.0M     0.0M     5.0M    0%  
	  2036725         4   2036721    0% 
/run/user/0          tmpfs   tmpfs      
	rw,nosuid,nodev,relatime,size=1629380k,mode=700                   
	    1.6G     0.0G     1.6G    0%   100%  
	    1.6G     0.0G     1.6G    0%   100%  
	    1.6G     0.0G     1.6G    0%  
	  2036725         4   2036721    0% 
/run/user/1000       tmpfs   tmpfs      
	rw,nosuid,nodev,relatime,size=1629380k,mode=700,uid=1000,gid=1000 
	    1.6G     0.0G     1.6G    0%   100%  
	    1.6G     0.0G     1.6G    0%   100%  
	    1.6G     0.0G     1.6G    0%  
	  2036725        36   2036689    0% 
/sys/fs/cgroup       tmpfs   tmpfs      
	rw,mode=755                                                       
	    7.8G     0.0G     7.8G    0%   100%  
	    7.8G     0.0G     7.8G    0%   100%  
	    7.8G     0.0G     7.8G    0%  
	  2036725        18   2036707    0% 
/var/lib/docker/aufs ext4    /dev/sda1  
	rw,relatime,errors=remount-ro,data=ordered                        
	  901.2G   188.3G   712.9G   21%    79%  
	  901.2G   234.1G   667.1G   26%    74%  
	  855.4G   188.3G   667.1G   22%  
	 60014592   1372538  58642054    2%

c 选项逗号分割

使用 -c 选项分割输出

di -c
s,m,b,u,v,p,T
"/dev/sda1","/","901.2G","188.3G","667.1G",26%,"ext4"
"tmpfs","/dev/shm","7.8G","0.1G","7.6G",2%,"tmpfs"
"tmpfs","/run","1.6G","0.1G","1.5G",4%,"tmpfs"
"cgmfs","/run/cgmanager/fs","0.1M","0.0M","0.1M",0%,"tmpfs"
"tmpfs","/run/lock","5.0M","0.0M","5.0M",0%,"tmpfs"
"tmpfs","/run/user/0","1.6G","0.0G","1.6G",0%,"tmpfs"
"tmpfs","/run/user/1000","1.6G","0.0G","1.6G",0%,"tmpfs"
"tmpfs","/sys/fs/cgroup","7.8G","0.0G","7.8G",0%,"tmpfs"
"/dev/sda1","/var/lib/docker/aufs","901.2G","188.3G","667.1G",26%,"ext4"

c 是 --csv-output 的缩写，为了便于程序解析

t 参数增加统计行

-t 参数在最后增加统计行

di -t
Filesystem         Mount               Size     Used    Avail %Used  fs Type
/dev/sda1          /                 901.2G   188.4G   667.0G   26%  ext4   
tmpfs              /dev/shm            7.8G     0.1G     7.6G    2%  tmpfs  
tmpfs              /run                1.6G     0.1G     1.5G    4%  tmpfs  
cgmfs              /run/cgmanager/     0.1M     0.0M     0.1M    0%  tmpfs  
tmpfs              /run/lock           5.0M     0.0M     5.0M    0%  tmpfs  
tmpfs              /run/user/0         1.6G     0.0G     1.6G    0%  tmpfs  
tmpfs              /run/user/1000      1.6G     0.0G     1.6G    0%  tmpfs  
tmpfs              /sys/fs/cgroup      7.8G     0.0G     7.8G    0%  tmpfs  
/dev/sda1          /var/lib/docker   901.2G   188.4G   667.0G   26%  ext4   
                   Total               1.8T     0.4T     1.3T   26%

s 参数对结果排序

di -s 默认更具 mount point 输出

  • di -sm 默认 mount pont
  • di -sn 不排序，按照挂载表 /etc/fstab 中顺序
  • di -ss 按照特殊设备
  • di -st 根据 filesystem type
  • di -sr 逆序输出

排序方式可以组合使用，如：di –stsrm ：按照类型、设备、挂载点逆序排序。 di –strsrm ：按照类型、设备逆序、挂载点逆序排序。

f 选项自定义格式

di -fM
Mount               
/                   
/dev/shm            
/run                
/run/cgmanager/fs   
/run/lock           
/run/user/0         
/run/user/1000      
/sys/fs/cgroup      
/var/lib/docker/aufs

只打印 mount point

更多的 f 的选项可以直接参看 man di

总结

虽然 di 提供了比 df 更多更强大的功能，但是也有其缺点，大部分的 Linux 发行版默认是没有预装的。


2017-10-16 linux , 磁盘管理 , disk , df

从 Clonezilla 恢复系统学习 Linux 启动过程

最近又一次使用 Clonezilla 来克隆系统，和以往不同的是，这一次我是备份了整块硬盘到镜像，然后从镜像恢复系统到另外一块硬盘，而不是以往是复制一个分区，所以又产生了一些问题，所以有了这篇文章，一方面来记录一下中间遇到的问题，另一方面也学习巩固一下关于 Linux 启动过程中的必要流程。

基础知识

关于最基础的计算机启动过程也就不展开说，阮一峰，和网上大部分文章已经讲的非常清晰了，这里只简单的列举一些基础名词，必须要知道的概念。

BIOS

全称是 Basic Input Output System，也就是一块被写入开机程序的只读内存，电脑通电之后第一时间会读取的芯片。

POST

POST 不是 HTTP 请求方法的 POST，而是 Power On Self Test，开机自检，在通电之后 BIOS 加载后会自动执行。

MBR

MBR 是主引导分区，全称是 Master Boot Record，该分区决定该设备是否能够启动。如果设备能够启动，那么该设备第一个扇区，512 字节就需要表明该设备能够启动。

主引导记录告诉计算机去哪一块硬盘寻找操作系统，主引导记录由三部分组成，1-446 字节，调用系统机器码，447-510 字节，分区表，511-512 字节，主引导记录签名 （0x55,0xAA）。

mbr

GRUB

GRUB 是 Linux 下最流行的启动管理器，全称是 GRand Unified Bootloader。计算机在读取 MBR 前 446 字节机器码之后，将运行事先安装的启动管理器 boot loader 也就是 GRUB。

GRUB 设计兼容 multiboot specification，为了使得 GRUB 能够引导启动各种版本的 Linux。GRUB 也能够让用户选择从不同的 kernels 启动。Grub 的配置文件地址在 /boot/grub/grub.conf.

GRUB1 现在正在被 GRUB2 代替，Grub2 在 /boot/grub2/grub.cfg 配置。

所以总结来看，计算机通电之后，先通过 BIOS，到 MBR，通过 GRUB 引导操作系统启动。以上就是计算机 boot sequence 的过程。

System startup

通过 GRUB 引导启动操作系统，之后操作系统就会接管系统启动，操作系统启动过程也分为很多步骤。

Stage 1.0

BIOS 在 MBR 中搜索 boot record，因为主引导分区必须保证尽量小，所以通过 stage 1.0 找到 1.5 GRUB 引导，GRUB 引导必须在 boot record 和第一个分区之间，将 GRUB 加载到内存之后进入 stage 1.5.

Stage 1.5

上面提到 GRUB 必须在引导记录和磁盘第一个分区之间，这一块区域因为历史原因被预留，磁盘的第一个分区从 sector 63 开始，MBR 在 sector 0，所以留下了 62512 byte sectors，大概 31774 bytes，用来保存 core.img， core.img 只有 25389 字节，所以完全足够。

需要注意的是，/boot 目录需要存放在支持 GRUB 的文件系统上。stage 1.5 在找到 /boot 文件和加载必要的驱动之后执行。

Stage 2

GRUB stage 2 阶段会加载 Linux kernel 到内存中，kernel 和相关的文件在 /boot 目录中。kernel 文件都以 vmlinuz 开头。

kernel 都是压缩的格式以节省空间，当计算机解压并加载内核到内存之后，会加载 systemd，自此系统启动过程结束，内核和 systemd 都已经在运行。

systemd 是所有进程的创始者，他负责将系统启动至一个可工作的状态，他负责包括挂载系统文件，启动管理系统服务等等工作。

systemd 启动流程

首先 systemd 会尝试使用 /etc/fstab 中定义的内容挂载文件系统，包括定义的根分区，swap 分区文件等等。

# /etc/fstab: static file system information.
#
# Use 'blkid' to print the universally unique identifier for a
# device; this may be used with UUID= as a more robust way to name devices
# that works even if disks are added and removed. See fstab(5).
#
# <file system> <mount point>   <type>  <options>       <dump>  <pass>
# / was on /dev/sda1 during installation
UUID=3d1b7e3e-c184-4664-9555-2b088997f2c8 /              ext4    errors=remount-ro 0       1
# swap was on /dev/sda5 during installation
UUID=b99bf592-a25b-4ca0-b597-fc62e121aae1 none          swap    sw            0    0

关于 systemd 的启动顺序，可以参考阮一峰的这篇

修改 GRUB

默认情况下 GRUB 会有 10 秒时间来给用户选择系统，这个设置可以通过修改 /etc/default/grub 来修改。

GRUB_DEFAULT=0          # 默认启动的系统序号
GRUB_TIMEOUT=4          # 默认等待多久以预设系统开机

更新之后使用 sudo update-grub 来更新 GRUB。

GRUB Manual 手册中提供了完整的参数解释。

遇到的问题

No bootable device

使用 Clonezilla 复制硬盘所有分区到另外一块硬盘，而我这边遇到的情况是复制结束之后硬盘没有 boot 分区，导致 BIOS 无法找到主引导分区。

解决办法是使用 Clonezilla 的专家（高级）模式，在高级模式中会自动修复 grub 的问题

无法启动 Linux Mint 桌面

这个问题表现形式可能是各种各样的，开机黑屏，或者在 grub 引导之后出现各种乱码命令。对于这个问题的解决方法可能需要是修改 /etc/fstab ，将其中硬盘的 UUID ，通过 sudo blkid 查看获取后保证 /etc/fstab 中启动的硬盘是一块。可以参考之前的文章

reference


2017-09-25 linux , boot , mbr , uefi , bios , clonezilla

每天学习一个命令：使用 grep 查找文件内字符串

grep 在 man 手册中的解释是”print lines matching patterns”，也非常容易理解。

grep 名字的由来

在 unix 早期的编辑器中，如果要查找比如 junk 这个单词，需要输入 /junk/p 来打印找到的一个行，如果要找所有行，就使用 g/junk/p，g 是 global search 的意思。

这个功能被独立出来作为了命令，只做一件事情，就是全局搜索，并打印，叫做 grep，其实是 g/regular expression/p 的缩写，可以理解为 g/re/p，在 vi 或者 sed 中类似的功能也经常能见到。

使用

比如说在当前目录下，搜索文件中包含的 password 词

grep password *

grep 会自动在当前目录下搜索并将包含 password 行打印出来，所以千万不要在本地文件中存放密码一类的敏感信息，这一无异于将密码写在显示器上。

使用 -i 来忽略大小写

grep -i password *

这一行命令会匹配，比如 Password，PASSWORD 等等。

将 grep 作为过滤器来过滤标准输出的内容

cat /etc/passwd | grep 'sshd'

强制让 grep 输出文件名

grep 'sshd' /etc/passwd /dev/null

这时 grep 会打印文件名，冒号，结果

显示不包含正则的行

grep -v 'junk' *

再比如，如果想要设置 every 但是不想搜索 everyone，everybody 和 everywhere 可以使用

grep every * | grep -v one | grep -v body | grep -v where

扩展

在 grep 之上，后人又开发了很多很有用的命令，比如不解压的情况下搜索压缩包中的内容，再比如简便版的 ack-grep

reference


2017-09-23 grep , linux , egrep

jinja2 笔记

jinja2 是基于 Python 的模板引擎。

种类

注意下面的 \ 是因为模板需要转义，使用时需要去掉，另外大括号和 % 之间的空格也需要去掉。

\{\% ... \%\}  Statements 控制结构，比如 if/elif/else for-loops，macros，block 等等
\{\{ ... \}\}  Expressions 表达式，用来输出结果
\{\# ... \#\}  Comments 注释
\#  ... \#\#  Line Statements

表达式及过滤器

`` 结构表示一个变量

过滤器用法

Hello,

常用的过滤器

过滤器 说明
safe 渲染值时不转义
capitalize 把值的首字母转换成大写，其他字母转换成小写
lower 把值转换成小写形式
upper 把值转换成大写形式
title 把值中每个单词的首字母都转换成大写
trim 把值的首尾空格去掉
striptags 渲染之前把值中所有的 HTML 标签都删掉
length 输出长度

完整的过滤器清单可以在文档中找到：http://jinja.pocoo.org/docs/templates/#builtin-filters

控制结构

用来控制流程

常见的 if-else

{ % if user % }
    Hello, !
{ % else % }
    Hello, Stranger!
{ % endif % }

for 循环

<ul>
{ % for comment in comments % }
    <li></li>
{ % endfor % }
</ul>

宏，类似方法

{ % macro render_comment(comment) % }
    <li></li>
{ % endmacro % }

<ul>
{ % for comment in comments % }
    
{ % endfor % }
</ul>

保存到文件中使用 import

{ % import 'macros.html' as macros % }
<ul>
    { % for comment in comments % }
        
    { % endfor % }
</ul>

需要多次使用的模板可以单独放在文件中，然后 使用 include

{ % include 'common.html' % }

模板继承，先定义父模板

<html>
<head>
    { % block head % }
        <title>{ % block title % }{ % endblock % } - My Application</title>
    { % endblock % }
</head>
<body>
{ % block body % }
{ % endblock % }
</body>
</html>

然后继承

{ % extends "base.html" % }
{ % block title % }Index{ % endblock % }
{ % block head % }
    
    <style>
    </style>
{ % endblock % }
{ % block body % }
    <h1>Hello, World!</h1>
{ % endblock % }

表单

WTForms 支持的字段类型

字段类型 说明
StringField 文本字段
TextAreaField 多行文本字段
PasswordField 密码文本字段
HiddenField 隐藏文本字段
DateField 文本字段，值为 datetime.date 格式
DateTimeField 文本字段，值为 datetime.datetime 格式
IntegerField 文本字段，值为整数
DecimalField 文本字段，值为 decimal.Decimal
FloatField 文本字段，值为浮点数
BooleanField 复选框，值为 True 和 False
RadioField 一组单选框
SelectField 下拉列表
SelectMultipleField 下拉列表，可选择多个值
FileField 文件上传字段
SubmitField 表单提交按钮
FormField 把表单作为字段嵌入另一个表单
FieldList 一组指定类型的字段

WTForms 支持的验证函数

验证函数 说明
Email 验证电子邮件地址
EqualTo 比较两个字段的值；常用于要求输入两次密码进行确认的情况
IPAddress 验证 IPv4 网络地址
Length 验证输入字符串的长度
NumberRange 验证输入的值在数字范围内
Optional 无输入值时跳过其他验证函数
Required 确保字段中有数据
Regexp 使用正则表达式验证输入值
URL 验证 URL
AnyOf 确保输入值在可选值列表中
NoneOf 确保输入值不在可选值列表中

在模板中使用

<form method="POST">

 

</form>

2017-09-22 python , flask , jinja2 , template , web

Python 笔记之赋值语句和表达式

赋值语句比较简单，Learning Python 这本书中对赋值语句介绍比较详细，分类也讲述的比较细，这篇文章就只简单的记录一些容易混乱的知识点，并不记录所有赋值语句需要注意的点。

Augmented assignment and shared references

在之前的文章中就交代过共享引用是需要特别注意的，在 augmented assignment 中也是

>>> L = [1, 2]
>>> M = L                           # L M 共享同一个对象
>>> L = L + [3, 4]                  # Concatenation 会创建新的对象
>>> L, M                            # 所以他们的值不相同
([1, 2, 3, 4], [1, 2])

>>> L = [1, 2]
>>> M = L                           # Share
>>> L += [3, 4]                     # 但是 `+=` 其实用的是 extend 方法，所以是原地修改
>>> L, M
([1, 2, 3, 4], [1, 2, 3, 4])

Expression Statements and In-Place Changes

表达式同样也分为很多种

>>> L = [1,2]
>>> L.append(3)
>>> L
[1, 2, 3]

不过需要注意的是，比如 append() 方法并没有返回值，所有返回的 L 会是 None

>>> L = L.append(4)
>>> L
None

2017-09-20 python , notes , assignment , expression

Maven 介绍

Maven 是一个项目管理工具，主要用于项目构建，依赖管理，项目信息管理。自动化构建过程，从清理、编译、测试和生成报告、再到打包和部署。Maven 通过一小段描述信息来管理项目。

Maven 安装

安装之前先把 JDK 环境配置好。

Debian/Ubuntu/Linux Mint 下

sudo apt install maven

如果要手动安装则按照下面步骤

  • 下载 Maven 最新安装包，地址 http://Maven.apache.org/download.cgi 比如 apache-Maven-3.3.9-bin.tar.gz
  • tar -zxvf apache-Maven-3.3.9-bin.tar.gz
  • 将 apache-Maven-3.3.9 目录移动到 /usr/local 目录 命令： sudo mv apache-maven-3.3.9/ /usr/local/

  • root 身份修改配置命令 sudo vi ~/.bashrc 在文件最后添加：

      #set Maven environment
  M2_HOME=/usr/local/apache-maven-3.3.9
  export Maven_OPTS="-Xms256m -Xmx512m"
  export PATH=$M2_HOME/bin:$PATH

    保存并关闭。

  • 使配置生效必须重启机器或者在命令行输入： source ~/.bashrc
  • 查看 Maven 是否安装成功： mvn -version

如果进行了上面步骤在任意目录中 mvn 命令不能使用，可以在 /etc/profile 文件后面加入下面三行 sudo vim ~/.bashrc

然后输入以下内容

Maven_HOME=/usr/local/apache-maven-3.3.9
export Maven_HOME
export PATH=${PATH}:${Maven_HOME}/bin

设置好 Maven 的路径之后，需要运行下面的命令 source ~/.bashrc 使刚刚的配置生效

Maven 作用

Maven 最熟悉的一个概念就是 POM，Maven 项目会有一个 pom.xml 文件， 在这个文件里面添加相应配置，Maven 就会自动帮你下载相应 jar 包

<dependency>
  <groupId>com.google.firebase</groupId>    项目名
  <artifactId>firebase-admin</artifactId>   项目模块
  <version>5.3.1</version>                  项目版本
</dependency>

项目名 - 项目模块 - 项目版本 三个坐标定义了项目在 Maven 世界中的基本坐标，任何 jar，pom， war 都是基于这些坐标进行区分的。

  • groupId 定义了项目组，组和项目所在组织或公司，或者开源项目名称，一般为公司域名反写，比如 com.google.firebase 等等

  • artifactId 定义了 Maven 项目的名称，在组中的唯一 ID，在同一个项目中可能有不同的子项目，可以定义不同的 artifactId。 artifactId 也是构建完成项目后生成的 jar 包或者 war 包的文件名的一部分。

  • version 顾名思义，就是项目的版本号，如果项目维发布，一般在开发中的版本号习惯性加上 SNAPSHOT， 比如 1.0-SNAPSHOT

根据上面的例子，比如上面定义的 Maven 坐标，可以在对应的中央仓库中 https://repo1.maven.org/maven2/com/google/firebase/firebase-admin/5.3.1/ 目录下找到对应的文件。

  • scope 定义了依赖范围，如果依赖范围为 test ，那么该依赖只对测试有效，也就是说在测试代码中引入 junit 有效，在主代码中用 junit 会造成编译错误。如果不声明依赖范围则默认为 compile ，表示该依赖对主代码和测试代码都有效。

Maven 有以下几种依赖范围：

  • compile 编译依赖，在编译、测试、运行时都有效
  • test 测试依赖，只对于测试 classpath 有效， JUnit 典型
  • provided 已提供依赖，只在编译和测试有效，运行时无效， servlet-api 编译和测试项目时需要该依赖，但是在运行项目时，由于容器已经提供，不需要 Maven 重复引入
  • runtime 运行时依赖，对于测试和运行有效，编译主代码无效， JDBC 驱动实现，项目主代码编译只需要 JDK 提供的 JDBC 接口，只有执行测试或者运行项目才需要实现上述接口的具体 JDBC 驱动
  • system 系统依赖范围，和 provided 范围依赖一致，但是使用 system 范围的依赖时必须通过 systemPath 元素显示地指定依赖文件的路径。
  • import 导入依赖，一般不用

依赖范围和 classpath 的关系

依赖范围 Scope 编译 classpath 有效 测试 classpath 有效 运行 classpath 有效 例子
compile Y Y Y spring-core
test - Y - junit
provided Y Y - servlet-api
runtime - - Y JDBC 驱动
system Y Y - 本地的， Maven 仓库之外的类库

Maven 依赖调解 Dependency Mediation ，第一原则：路径最近者优先；第二原则：第一声明者优先。

SNAPSHOT 快照版本只应该在组织内部的项目或者模块之间的依赖使用，组织对于这些快照版本的依赖具有完全的理解和控制权。项目不应该依赖于任何组织外部的快照版本，由于快照的不稳定性，依赖会产生潜在的危险，即使项目构建今天是成功的，由于外部快照版本可能变化，而导致未来构建失败。

Maven 核心概念 仓库

在上面介绍 Maven 的作用的时候提到了 Maven 的两个核心概念：坐标和依赖，这也是 Maven 首要解决的问题。这里要引入 Maven 另外一个核心概念：仓库。 Maven 时间中通过坐标来定位依赖，Maven 通过仓库来统一管理这些依赖。

Maven 项目的每一个构件对应着仓库的路径为： groupId/artifactId/version/artifactId-version.packageing

Maven 的仓库分为远程仓库和本地仓库，当第一次运行 Maven 命令时，需要网络连接，从远程仓库下载可用的依赖和插件。而当以后在运行 Maven 命令的时候，Maven 会自动先检查本地 ~/.m2/repository 目录下的依赖，如果本地有缓存优先从本地获取，在找不到的情况下去远程仓库寻找。

常用的在线 maven 依赖查看网站

Maven 核心概念 生命周期和插件

Maven 的生命周期是抽象的，实际行为都有插件完成。

clean 生命周期

清理项目，包含三个阶段

  • pre-clean 执行清理前需要完成的工作
  • clean 清理上一次构建生成的文件
  • post-clean 执行一次清理后需要完成的工作

default 生命周期

定义了真正构建时所需要执行的步骤

  • validate 验证工程是否正确，所有需要的资源是否可用。
  • initialize
  • generate-sources
  • process-sources 主要资源文件
  • generate-resources
  • process-resources
  • compile 编译主源码
  • process-classed
  • generate-test-sources
  • process-test-sources 测试资源
  • generate-test-resources
  • process-test-resources
  • test-compile 编译项目测试代码
  • process-test-classes 已发布的格式，如 jar，将已编译的源代码打包
  • prepare-package
  • pre-integration-test 在集成测试可以运行的环境中处理和发布包
  • post-integration-test
  • verify 运行任何检查，验证包是否有效且达到质量标准。
  • install 将包安装到 Maven 本地仓库，供本地 Maven 项目使用
  • deploy 复制到远程仓库，供其他人使用

site 生命周期

建立和发布项目站点

  • pre-site 生成项目站点之前需要完成的工作
  • site 生成站点文档
  • post-site 生成之后
  • site-deploy 生成的站点发布到服务器上

具体的流程可以参考下图

Maven 生命周期

Maven 项目文件结构

下面是一个标准的 Maven 工程

src/main/java - 存放项目.java 文件；
src/main/resources - 存放项目资源文件；
src/test/java - 存放测试类.java 文件；
src/test/resources - 存放测试资源文件；
target - 项目输出目录；
pom.xml - Maven 核心文件（Project Object Model）；

Maven 常用命令

mvn archetype：create 创建 Maven 项目
mvn compile 编译源代码
mvn deploy 发布项目
mvn test-compile 编译测试源代码
mvn test 运行应用程序中的单元测试
mvn site 生成项目相关信息的网站
mvn clean 清除项目目录中的生成结果
mvn package 根据项目生成的 jar
mvn install 在本地 Repository 中安装 jar
mvn eclipse:eclipse 生成 eclipse 项目文件
mvn jetty:run 启动 jetty 服务
mvn tomcat:run 启动 tomcat 服务
mvn clean package -DMaven.test.skip=true 清除以前的包后重新打包，跳过测试类
mvn clean package 清除以前的包后重新打包

reference


2017-09-20 maven , java , build , management

IntelliJ IDEA 中使用 Resin 调试

平时开发环境使用的是 jetty，而 Java Web 有一个更好更快的服务器 Resin，这篇文章就来说一下什么是 Resin，以及在 Debug 中如何使用。

什么是 Resin

Resin是一个提供高性能的，支持 Java/PHP 的应用服务器。目前有两个版本：一个是GPL下的开源版本，提供给一些爱好者、开发人员和低流量网站使用；一种是收费的专业版本，增加了一些更加适用于生产环境的特性。

Resin也可以和许多其他的web服务器一起工作，比如Apache Server和IIS等。Resin支持Servlets 2.3标准和JSP 1.2标准。熟悉ASP和PHP的用户可以发现用Resin来进行JSP编程是件很容易的事情。Resin支持负载平衡，可以增加WEB站点的可靠性。方法是增加服务器的数量。比如一台Server的错误率是1%的话，那么支持负载平衡的两个Resin服务器就可以使错误率降到0.01%。到目前为止，Resin对WEB应用的支持已经远远超过Tomcat等各种大型的Server。

Resin 安装

在 Resin 的官方 quick start 教程中有各大平台详细的安装指导。我在使用 apt 安装时没有成功，这里就记录下手工安装的过程。

在 http://caucho.com/download 网址下载， Resin 有两个版本， Pro 版和GPL开源版，个人使用开源基础版本已经足够。安装过程如下：

  1. 安装JDK 6 或者以上版本，将 java 可执行程序配置到环境变量 JAVA_HOME 中
  2. tar -vzxf resin-4.0.x.tar.gz 根据下载的最新版本解压
  3. cd resin-
  4. ./configure 更多参数参考 configure options
  5. make
  6. sudo make install
  7. 执行 sudo resinctl start, 或者运行 java -jar lib/resin.jar start
  8. 浏览 http://localhost:8080

可以使用 sudo resinctl stop 来停止运行，更多内容可以参考官方指南 。

IntelliJ IEDA 中使用 Resin 调试

第一步，添加 Resin Local 选项，在 IDEA 中 Run/Debug Configuration 中添加 Resin Local 选项

resin-local

点击configure按钮，在弹出窗Application Servers中选择部分一中安装的Resin目录路径和目录下Resin的配置文件路径。

resin-configure

Run/Debug Configurations 中Server页面配置，基本都是默认。

Run/Debug Configurations 中Deployment页面配置,注意红色方框部分选择。选择resin.xml而不是JMX否则项目的index路径是localhost:8080/appname/ 而不是localhost:8080/

resin-deplyment

在Resin的服务器配置下 Depolyment中 Depolyment method：有 JMX 和resin.xml 两种选择, JMX 是把项目打包的文件放在resin 服务器下webapp下 只有在服务器启动时 才把项目给拷贝过去 无法在intellij中实时更新; resin.xml 是在C盘Temp 目录下 copy了一份resin.xml的配置文件 然后把服务器目录空间指向了你的项目工作空间 可以实现IntelliJ 修改实时更新。IntelliJ 默认的选择是JMX 所以我们要选中resin.xml模式。同时当项目 Artifacts 指向的目录是 ROOT 时 上图中的Use default context name(always true if depolyment method is JMX)取消勾选

执行build，得到war文件。执行resin run/debug，会自动在你选择的浏览器中打开项目index页面。也可以在IDEA下方的Application Servers面板中进行Resin的启动，停止等操作。Resin启动的打印信息也在此窗口显示。

run-resin


2017-09-19 Resin , IntelliJ , Java

Python 中 subprocess.call() vs os.system() 区别

在 Python 中调用系统命令可以使用两种方法，一种是 os 模块中的 system() 方法，一种是 subprocess 模块中的 call() 方法。

os.system()

这个方法会接受一个字符串命令，然后在 subshell 中执行，通常是 linux/OSX 下的 bash ，或者 Windows 下面的 cmd.exe。根据官方的文档，os.system() 方法时使用标准 C 方法 system() 来调用实现的，所以存在和 C 方法中一样的限制。

os.system("python –version")

举例

import os
cmd = "git --version"
returned_value = os.system(cmd)  # returns the exit code in unix
print('returned value:', returned_value)

subprocess.call()

默认情况下不使用 shell，他只是简单的执行传入的字符串

运行带参数的命令需要传 list

subprocess.call(["python", "–version"])

subprocess.call() 当使用 shell=True 时和 os.system() 一样使用 shell

subprocess.call(["python", "–version"], shell=True)

举例

import subprocess

cmd = "date"
# returns output as byte string
returned_output = subprocess.check_output(cmd)
# using decode() function to convert byte string to string
print('Current date is:', returned_output.decode("utf-8"))

subproecess.Popen()

subproecess 模块中如果想要实现更加复杂的命令，可以使用 Popen()。popen() 会创建一个管道，fork 一个子进程，然后该子进程执行命令。返回值在标准 IO 流中，该管道用于父子进程间通信。父进程要么从管道读信息，要么向管道写信息，至于是读还是写取决于父进程调用 popen 时传递的参数（w 或 r）。

import subprocess
child = subprocess.Popen(['ping','-c','4','douban.com'])
child.wait()
print 'main process'

默认情况下，开启子进程之后不会等待 child 执行完成，需要使用 wait() 来等待子进程完成。

父进程对子进程还有其他的操作

child.poll()           # 检查子进程状态
child.kill()           # 终止子进程
child.send_signal()    # 向子进程发送信号
child.terminate()      # 终止子进程

子进程的标准输入、标准输出和标准错误

child.stdin
child.stdout
child.stderr

举例

import subprocess
child1 = subprocess.Popen(["ls","-l"], stdout=subprocess.PIPE)
print child1.stdout.read()

使用 subprocess 创建子进程能够重定向 stdin stdout，总体来说要比 os.system() 更加强大。

reference


2017-09-18 python , subprocess , system , subshell

写了一个推送图书到 Kindle 的 bot

最近因为好奇所以大致的看了一下 Telegram 的 bot，很早 就开始用 Telegram 但事实上，我大部分情况下就是将 Telegram 作为一个跨平台同步工具和备份工具来使用，直到最近因为 Ingress 的一些朋友和一个图书群我对 Telegram 才有了更多的使用，也在 Telegram 发现了每周会推送一本书的 Channel。

所以我想照着有一个叫做 to_kindle_bot 的号自己写了一个将图书发送到 kindle 邮箱的机器人，bot 要实现的功能很简单，就是将图书资源发送给 bot 之后将图书发送邮件推送到关联的 kindle 邮箱。将任务拆解开，主要的步骤也比较简单

  • 首先要了解的就是 Telegram bot 的 API
  • 再次存储用户的 kindle 邮箱
  • 再次就是将文件获取之后发送到对应的邮箱中

再做的过程中，我又增加了一些功能

  • 比如，在 bot 获取到图书之后会自动解析这本图书的 meta 信息和封面信息
  • 比如，kindle 有些格式不支持，所以要提前进行转码

所以一一解决这些问题即可。

Telegram Bot API

这一部分其实也没有什么要多说的，botFather 会创建好 bot，然后我用 Python 的 python-telegram-api。基本上也都是非常成熟的文档。

存储邮箱

因为早之前就已经做了一个图书相关的网站，所以理所当然的将用 telegram uid 和用户的 kindle 邮箱做了以下映射。

发送邮件

这部分其实之前也做过，所以直接使用 Flask mail 或者标准库里面的 smtp 去发就行了，邮件服务早之前 也做过调查，也是现成的用 mailgun 了。

获取图书信息

这一部分确实花了我一些精力，使用 python 的 ebooklib 库来解析了 epub 格式的电子书，也因为 epub 格式鱼龙混杂，所以修了几个 bug，但是 epub 格式的图书解析确实解决了，但是 mobi 格式我是没有找到任何方式来解析，不过幸好，调研的过程中发现了 Calibre 自带的 ebook-meta 命令行工具，在测试之后发现非常好用，支持的格式也非常多，几乎能够支持 99% 的情况，那这样一来获取图书 meta 和封面的工作也 OK。

图书格式转码

这部分一开始准备想要用 Amazon 提供的 kindlegen 命令行工具来实现的，但是发现他只能够将 其他的格式转为 mobi 格式，那这样局限就比较大了，虽然能够 cover 我现在的需求，但是如果以后有 mobi 格式转 epub 格式的需求，其实就有了问题，不够幸好还是 Calibre 这个强大的工具，提供了 ebook-convert 命令行工具，能够转化非常多的格式，所以理所当然的就采用了它。

至此就完成了 bot 90% 的工作，剩下就是组织一些文案和 bot 的零星的 bug 问题，所以可以试用下 @kindlepush_bot。

bot 主要命令功能

bot 现在为止一共有 start help email settings 这几个功能，除开 settings 功能还未完成， email 命令用来设置 kindle 邮箱，start 和 help 命令用来显示帮助，settings 功能我设想可以让用户选择一个频率，bot 会自动在这个频率下发送一本书到 kindle 邮箱中。

另外如果大家喜欢电子书，我用 Flask 练手的电子书网站 http://book.einverne.info 也欢迎使用。


2017-09-17 kindle , telegram , bot , python-telegram-api

电子书

Google+

文章分类

最近文章

  • gulp 工具简单使用 Gulp 是基于 Node.js 的前端构建工具，可以通过 Gulp 实现前端代码编译，压缩，测试，图片压缩，浏览器自动刷新，等等，Gulp 提供了很多插件。
  • 使用 nltk 词形还原 今天在用 mdx-server 将 mdx 文件导出 HTTP 接口时发现 mdx-server 项目并不支持类似与 GoldenDict Morphology 构词法一样的规则，所以只能够在 mdx-server 外自行处理英语单词的词形变化，搜索一圈之后发现了 NLTK。
  • AngularJS 学习笔记 如果要说 AngularJS 是什么，那么用这些关键词就能够定义，单页面，适合编写大量 CRUD 操作，MVC
  • Aviator 轻量 Java 表达式引擎 Aviator 是一个轻量级、高性能的 Java 表达式执行引擎，它动态地将表达式编译成字节码并运行。
  • 后知后觉之 iOS 内置字典 用了近两年 iOS，中途也因为学习需要下载了很多的字典，但是没想到的是 iOS 竟然内置有版权的字典。