前言

Flask 是 Python 开发的轻量 Web 框架，有多轻量呢？10 行以内就可以开发一个 Web 服务，不过这只能用来做演示，今天我就用 1 个小时来开发一个用于生产环境的短信微服务。以下是我们生产环境脱敏后直接可用的服务代码，绝非示例教程。

为什么要开发短信微服务？

短信服务我们都是依赖公有云的实现，通过公有云的 API 直接调用，那为什么还要自己封装呢？

因为微服务环境下我们要减少代码的重复量，如果有多个微服务需要使用短信服务，那就要复制多遍代码，把公有云的 API 包装成我们自己的微服务 API 可以将代码的复制减少为一行 Http 请求。
调用 API 的 accesskey 和 secret 不需要复制给多个服务，减少安全风险。
可以根据我们的业务需求加入共用的业务逻辑。

多了一层调用有没有性能影响？

多了一层调用是多了一个网络请求，但是影响微乎其微。我们不可能因为面向对象的方式太多调用就写逐行执行的代码吧。

公有云短信服务本就是异步调用，错误处理也是异步回调的方式。
微服务内部网络的调用应该是非常快的，可以同虚拟机部署或者同机房部署。

开始

首先我们建立项目的骨架。

为什么要建立项目的骨架呢？

因为 Flask 太过于轻量，所以例如配置、路由等规范需要由开发人员自己定义。一般成熟的开发团队都有自己的一套开发骨架，要统一配置，统一开发规范，统一集成相关系统等。我这里就分享一套适用于生产环境的非常简单的开发骨架。

新建一个项目目录，然后在里面建立 app 和 config 两个 Python 目录。app 用于存放业务相关代码，config 用于存放配置相关代码。

配置类

在 config/config.py 中添加如下内容，配置的设计因人而异，Flask 也没有做任何限制。我这里的设计是使用 BaseConfig 作为配置基类，存放所有共用的配置，而不同的环境使用不同的配置子类，子类只需要修改特定的值就可以，便于查看。

如果配置的值需要在运行是注入（如数据库连接等），则可以使用环境变量的方式（如下面的 SECRET_KEY），我同时使用 or 提供了没有环境变量的默认值。

import os


class BaseConfig:
    """
    配置基类，用于存放共用的配置
    """
    SECRET_KEY = os.environ.get('SECRET_KEY') or os.urandom(16)
    DEBUG = False
    TESTING = False


class ProductionConfig(BaseConfig):
    """
    生产环境配置类，用于存放生产环境的配置
    """
    pass


class DevelopmentConfig(BaseConfig):
    """
    开发环境配置类，用于存放开发环境的配置
    """
    DEBUG = True


class TestingConfig(BaseConfig):
    """
    测试环境配置类，用于存放开发环境的配置
    """
    DEBUG = True
    TESTING = True


registered_app = [
    'app'
]

config_map = {
    'development': DevelopmentConfig,
    'production': ProductionConfig,
    'testing': TestingConfig
}

至于后面的 registered_app 和 config_map 有什么用？可以做自动注入，这个我后面会讲。

然后我加一个日志的配置，日志的配置非常重要，不同的开发团队往往有一套规范的日志配置模版，一般不会改变，所以可以直接定义在代码里，也可以用配置文件的方式。

config/logger.py

from logging.config import dictConfig


def config_logger(enable_console_handler=True, enable_file_handler=True, log_file='app.log', log_level='ERROR',
                  log_file_max_bytes=5000000, log_file_max_count=5):
    # 定义输出到控制台的日志处理器
    console_handler = {
        'class': 'logging.StreamHandler',
        'formatter': 'default',
        'level': log_level,
        'stream': 'ext://flask.logging.wsgi_errors_stream'
    }
    # 定义输出到文件的日志处理器
    file_handler = {
        'class': 'logging.handlers.RotatingFileHandler',
        'formatter': 'detail',
        'filename': log_file,
        'level': log_level,
        'maxBytes': log_file_max_bytes,
        'backupCount': log_file_max_count
    }
    # 定义日志输出格式
    default_formatter = {
        'format': '[%(asctime)s] %(levelname)s in %(module)s: %(message)s'
    }
    detail_formatter = {
        'format': '[%(asctime)s] %(levelname)s in %(module)s: %(message)s'
    }
    handlers = []
    if enable_console_handler:
        handlers.append('console')
    if enable_file_handler:
        handlers.append('file')
    d = {
        'version': 1,
        'formatters': {
            'default': default_formatter,
            'detail': detail_formatter
        },
        'handlers': {
            'console': console_handler,
            'file': file_handler
        },
        'root': {
            'level': log_level,
            'handlers': handlers
        }
    }
    dictConfig(d)

上面就是一个典型的 Python 日志配置方法，把可变的部分定义为参数（日志文件、级别等），定义了两个日志处理器（文件和控制台），使用时只需要调用这个方法即可。

应用类

定义好配置，我们就开始创建我们的 Flask 应用了。用过 Flask 的同学知道，创建 Flask 应用只需要一行代码。

app = Flask(__name__)

但这不是生产可用的方式，为了生产和测试方便，我们需要用一个方法获取这个 app 对象。

def create_app(conf=None):
    # initialize logger
    register_logger()
    # check instance path
    instance_path = os.environ.get('INSTANCE_PATH') or None
    # create and configure the app
    app = Flask(__name__, instance_path=instance_path)
    if not conf:
        conf = get_config_object()
    app.config.from_object(conf)
    # ensure the instance folder exists
    if app.instance_path:
        try:
            os.makedirs(app.instance_path)
        except OSError:
            pass
    # register app
    register_app(app)
    return app

这里做了几个事情，一是注册日志类，二是载入配置对象，三是创建 instance 目录，四是注册应用业务。

为什么注册日志要放在第一行？

不少开发人员会把日志的配置放在配置类里，这个没太大问题，只是越早注册日志，你的日志就会越早开始收集。如果载入配置类后才配置日志，那如果创建 app 时报错就无法被我们定义的日志收集器收集到了。

注册日志的方法可以这样写

def register_logger():
    log_level = os.environ.get('LOG_LEVEL') or 'INFO'
    log_file = os.environ.get('LOG_FILE') or 'app.log'
    config_logger(
        enable_console_handler=True,
        enable_file_handler=True,
        log_level=log_level,
        log_file=log_file
    )

我还是从环境变量里获取配置，并调用之前的配置函数配置日志。

载入配置对象的方法。

def get_config_object(env=None):
    if not env:
        env = os.environ.get('FLASK_ENV')
    else:
        os.environ['FLASK_ENV'] = env
    if env in config.config_map:
        return config.config_map[env]
    else:
        # set default env if not set
        env = 'production'
        return config.config_map[env]

从 FLASK_ENV 这个环境变量获取运行的环境，然后根据之前配置类里的 config_map 获取对应的配置类，实现配置类的载入。

最后就是注册我们的业务代码。

def register_app(app):
    for a in config.registered_app:
        module = importlib.import_module(a)
        if hasattr(module, 'register'):
            getattr(module, 'register')(app)

这里就用到了配置类里的 registered_app 列表，这里定义了要载入的模块，对于微服务来说，一般只有一个模块。

我这里还需要 app/__init__.py 文件里有个 register 方法，这个方法来执行具体的注册操作，例如注册 Flask 蓝图。

def register(app):
    api_bp = Blueprint('api', __name__, url_prefix='/api')
    app.register_blueprint(api_bp)

为什么要搞个 register 方法？

因为每个业务模块有自己的路由、ORM 或蓝图等，这是业务自己的代码，必须与骨架解耦。用一个特定的方法作为规范一是便于自定义的代码扩展，二是便于团队理解，不需要灵活的配置，这里约定大于配置。当然你可以有自己的另一套实现。

我把上面的代码整理为 application.py 模块

import os
import importlib
from flask import Flask
from config.logger import config_logger
from config import config


def register_logger():
    log_level = os.environ.get('LOG_LEVEL') or 'INFO'
    log_file = os.environ.get('LOG_FILE') or 'app.log'
    config_logger(
        enable_console_handler=True,
        enable_file_handler=True,
        log_level=log_level,
        log_file=log_file
    )


def register_app(app):
    for a in config.registered_app:
        module = importlib.import_module(a)
        if hasattr(module, 'register'):
            getattr(module, 'register')(app)


def get_config_object(env=None):
    if not env:
        env = os.environ.get('FLASK_ENV')
    else:
        os.environ['FLASK_ENV'] = env
    if env in config.config_map:
        return config.config_map[env]
    else:
        # set default env if not set
        env = 'production'
        return config.config_map[env]


def create_app_by_config(conf=None):
    # initialize logger
    register_logger()
    # check instance path
    instance_path = os.environ.get('INSTANCE_PATH') or None
    # create and configure the app
    app = Flask(__name__, instance_path=instance_path)
    if not conf:
        conf = get_config_object()
    app.config.from_object(conf)
    # ensure the instance folder exists
    if app.instance_path:
        try:
            os.makedirs(app.instance_path)
        except OSError:
            pass
    # register app
    register_app(app)
    return app


def create_app(env=None):
    conf = get_config_object(env)
    return create_app_by_config(conf)

这里提供了 create_app_by_config 方法用于从配置类直接创建 app 对象，主要是便于单元测试时直接注入特定的配置类。

我们的骨架基本上就成型了，包括了最基础的配置类、日志配置和应用注册机制。然后就可以运行我们的 Flask 应用了。

开发测试

Flask 提供了 flask run 命令来运行测试应用，不过还需要提供 FLASK_APP 和 FLASK_ENV 两个环境变量来启动，这步我们也可以简化下。

编写 run.py

import click
from envparse import env
from application import create_app


@click.command()
@click.option('-h', '--host', help='Bind host', default='localhost', show_default=True)
@click.option('-p', '--port', help='Bind port', default=8000, type=int, show_default=True)
@click.option('-e', '--env', help='Running env, override environment FLASK_ENV.', default='development', show_default=True)
@click.option('-f', '--env-file', help='Environment from file', type=click.Path(exists=True))
def main(**kwargs):
    if kwargs['env_file']:
        env.read_envfile(kwargs['env_file'])
    app = create_app(kwargs['env'])
    app.run(host=kwargs['host'], port=kwargs['port'])


if __name__ == '__main__':
    main()

这里用 click 创建了一个简单的命令行脚本，可以通过命令行参数直接启动一个测试用服务。当然默认参数直接可用，使用 python run.py 或者 IDE 里右键运行即可。同时，还提供了 env-file 选项，用户可提供环境变量的文件。

为什么要使用环境变量文件？

因为生产环境和开发环境的许多配置是不同的，例如公有云密钥，数据库连接等，这些信息是绝对不能提交到 git 等版本控制软件的，所以我们可以创建一个 .env 文件如下

ACCESS_KEY=xxx
ACCESS_SECRET=xxx

把这个文件加入 gitignore 中，然后使用 --env-file 载入这个文件就可以在开发环境中直接使用了，而不需要每次都手动输入了。

部署

生产环境我们肯定不会使用测试的方式启动，需要类似 gunicorn 等工具启动一个正式服务，我们也可以使用 Docker 等容器技术把生产部署过程自动化。

编写 server.py

from application import create_app

app = create_app()

这里很简单，创建一个 Flask app 对象即可，然后可以通过 gunicorn server:app 启动。

编写 requirements.txt 文件，用于自动安装依赖。后期可以把用到的依赖写进去。

flask
flask-restful
click
envparse
gunicorn

编写 Dockerfile 文件

FROM python:3.8

COPY . /opt
WORKDIR /opt
RUN pip install --no-cache-dir -r requirements.txt
CMD ["gunicorn", "-b", "0.0.0.0:80", "server:app"]

然后就可以使用如下命令用 Docker 启动服务容器了。

docker build -t myapp:0.1 .
docker run -d --name myapp -p 80:80 myapp:0.1

至此，一个简单的 Flask 骨架就完成了，大家可以在下面看到完整的项目。

Github Flask 骨架示例

编写业务

上面大概用了 20 分钟搞了个 Flask 的骨架，对于开发团队来说，骨架只要开发一次，后续的项目直接克隆就行了。下面我们就来编写具体的发送短信业务。

使用哪个公有云？

实际业务中我们可能使用单一一个云，也可能混合使用多个云。在我们的实际业务中，具体用哪个公有云的服务，不是取决于我们，而是取决于谁的价格低，谁的优惠多，谁的功能强。😄

所以我们可以提取短信业务的共性写一个抽象类。短信服务的共同点主要有短信模版，签名，接收人，模版参数等。

一个简单的抽象类

class SmsProvider:

    def __init__(self, **kwargs):
        self.conf = kwargs

    def send(self, template, receivers, **kwargs):
        pass

然后有基于阿里云的实现，以下代码根据官方示例修改

class AliyunSmsProvider(SmsProvider):

    def send(self, template, receivers, **kwargs):
        from aliyunsdkcore.request import CommonRequest
        client = self.get_client(self.conf['app_key'], self.conf['app_secret'], self.conf['region_id'])
        request = CommonRequest()
        request.set_accept_format('json')
        request.set_domain(self.conf['domain'])
        request.set_method('POST')
        request.set_protocol_type('https')
        request.set_version(self.conf['version'])
        request.set_action_name('SendSms')
        request.add_query_param('RegionId', self.conf['region_id'])
        request.add_query_param('PhoneNumbers', receivers)
        request.add_query_param('SignName', self.conf['sign_name'])
        request.add_query_param('TemplateCode', self.get_template_id(template))
        request.add_query_param('TemplateParam', self.build_template_params(**kwargs))
        return client.do_action_with_exception(request)

    def get_template_id(self, name):
        if name in self.conf['template_id_map']:
            return self.conf['template_id_map'][name]
        else:
            raise ValueError('no template {} found!'.format(name))

    @staticmethod
    def get_client(app_key, app_secret, region_id):
        from aliyunsdkcore.client import AcsClient
        return AcsClient(app_key, app_secret, region_id)

    @staticmethod
    def build_template_params(**kwargs):
        if 'params' in kwargs and kwargs['params']:
            return json.dumps(kwargs['params'])
        else:
            return ''

然后在 BaseConfig 添加以下配置，是一些公有云 API 的基本配置，需要在运行是通过环境变量载入，其中 template_id_map 里的内容是模版的名称和对应的 ID，用于区分不同的短信模版，如验证码，推广等，名称作为参数供调用方使用，避免了直接传递 ID。

    # SMS config
    SMS_CONF = {
        'aliyun': {
            'provider_cls': 'app.sms.AliyunSmsProvider',
            'config': {
                'domain': 'dysmsapi.aliyuncs.com',
                'version': os.environ.get('ALIYUN_SMS_VERSION') or '2017-05-25',
                'app_key': os.environ.get('ALIYUN_SMS_APP_KEY'),
                'app_secret': os.environ.get('ALIYUN_SMS_APP_SECRET'),
                'region_id': os.environ.get('ALIYUN_SMS_REGION_ID'),
                'sign_name': os.environ.get('ALIYUN_SMS_SIGN_NAME'),
                'template_id_map': {
                    'captcha': 'xxx'
                }
            }
        }
    }

其中模版 ID，签名，App Key，App Secret 需要在阿里云控制台获取，模版和签名需要审核后才能获得。

同样的方法可以添加华为云的 API，也可直接从示例修改，只是华为云暂时没有 SDK，需要通过 API 调用，大同小异。

class HuaweiSmsProvider(SmsProvider):

    def send(self, template, receivers, **kwargs):
        header = {'Authorization': 'WSSE realm="SDP",profile="UsernameToken",type="Appkey"',
                  'X-WSSE': self.build_wsse_header(self.conf['app_key'], self.conf['app_secret'])}
        form_data = {
            'from': self.conf['sender'],
            'to': receivers,
            'templateId': self.get_template_id(template),
            'templateParas': self.build_template_params(**kwargs),
        }
        r = requests.post(self.conf['url'], data=form_data, headers=header, verify=False)
        return r

    def get_template_id(self, name):
        if name in self.conf['template_id_map']:
            return self.conf['template_id_map'][name]
        else:
            raise ValueError('no template {} found!'.format(name))

    @staticmethod
    def build_wsse_header(app_key, app_secret):
        now = time.strftime('%Y-%m-%dT%H:%M:%SZ')
        nonce = str(uuid.uuid4()).replace('-', '')
        digest = hashlib.sha256((nonce + now + app_secret).encode()).hexdigest()
        digest_base64 = base64.b64encode(digest.encode()).decode()
        return 'UsernameToken Username="{}",PasswordDigest="{}",Nonce="{}",Created="{}"'.format(app_key, digest_base64,
                                                                                                nonce, now)

    @staticmethod
    def build_template_params(**kwargs):
        if 'params' in kwargs and kwargs['params']:
            return json.dumps(list(kwargs['params'].values()))
        else:
            return ''

也是添加配置，最后的 BaseConfig 如下所示，其中 SMS_PROVIDER 配置指定 SMS_CONF 的键，指定我们现在使用的是哪个公有云服务：

class BaseConfig:
    SECRET_KEY = os.environ.get('SECRET_KEY') or os.urandom(16)
    DEBUG = False
    TESTING = False

    # SMS config
    SMS_PROVIDER = os.environ.get('SMS_PROVIDER')
    SMS_CONF = {
        'aliyun': {
            'provider_cls': 'app.sms.AliyunSmsProvider',
            'config': {
                'domain': 'dysmsapi.aliyuncs.com',
                'version': os.environ.get('ALIYUN_SMS_VERSION') or '2017-05-25',
                'app_key': os.environ.get('ALIYUN_SMS_APP_KEY'),
                'app_secret': os.environ.get('ALIYUN_SMS_APP_SECRET'),
                'region_id': os.environ.get('ALIYUN_SMS_REGION_ID'),
                'sign_name': os.environ.get('ALIYUN_SMS_SIGN_NAME'),
                'template_id_map': {
                    'captcha': 'xxx'
                }
            }
        },
        'huawei': {
            'provider_cls': 'app.sms.HuaweiSmsProvider',
            'config': {
                'url': os.environ.get('HUAWEI_URL'),
                'app_key': os.environ.get('HUAWEI_SMS_APP_KEY'),
                'app_secret': os.environ.get('HUAWEI_SMS_APP_SECRET'),
                'sender': os.environ.get('HUAWEI_SMS_SENDER_ID'),
                'template_id_map': {
                    'captcha': 'xxx'
                }
            }
        }
    }

其他的公有云也可以通过类似的方式添加。

然后我们添加一个方法，获取 Provider 的单例对象。这里使用 Flask 的 g 对象，把我们的 Provider 对象注册成全局的单例对象。

from flask import g, current_app
from werkzeug.utils import import_string


def create_sms():
    provider = current_app.config['SMS_PROVIDER']
    sms_config = current_app.config['SMS_CONF']
    if provider in sms_config:
        cls = sms_config[provider]['provider_cls']
        conf = sms_config[provider]['config']
        sms = import_string(cls)(**conf)
        return sms
    return None


def get_sms():
    if 'sms' not in g:
        g.sms = create_sms()
    return g.sms

这些都完成后，就可以添加一个视图类，这里用到了 Flask-Restful 库，生成 API 视图。

app/api/sms.py

import logging
from flask_restful import Resource, reqparse
from app.sms import get_sms


# 定义参数，参考 https://flask-restful.readthedocs.io/en/latest/reqparse.html
parser = reqparse.RequestParser(bundle_errors=True)
parser.add_argument('receivers', help='Comma separated receivers.', required=True)
parser.add_argument('template', help='Notification template name.', required=True)
parser.add_argument('params', help='Notification template params.', type=dict)


class Sms(Resource):

    def post(self):
        args = parser.parse_args()
        sms = get_sms()
        try:
            res = sms.send(**args)
        except Exception as e:
            logging.error(e)
            return {'message': 'failed'}, 500
        if res.status_code < 300:
            return {'message': 'send'}, 200
        else:
            logging.error('Send sms failed with {}'.format(res.text))
            return {'message': 'failed'}, 500

然后我们定义路由。

app/api/__init__.py

from flask import Blueprint
from flask_restful import Api
from app.api.health import Health
from app.api.sms import Sms


api_bp = Blueprint('api', __name__, url_prefix='/api')
api = Api(api_bp)

api.add_resource(Sms, '/sms')

最后记得在我们的应用 app 模块里注册蓝图。

app/__init__.py

from app.api import api_bp


# register blueprint
def register(app):
    app.register_blueprint(api_bp)

至此，我们的短信微服务就完成了。可以通过我们上面的方法进行测试和部署。

其中我们定义了一些环境变量，在测试时可通过环境变量文件载入，运行时可通过容器的环境变量载入。放在 instance 目录下是因为 instance 是我们默认的 Flask 实例目录，这个目录是不会提交到 git 里的。

instance/env

SMS_PROVIDER=huawei
HUAWEI_URL=https://rtcsms.cn-north-1.myhuaweicloud.com:10743/sms/batchSendSms/v1
HUAWEI_SMS_APP_KEY=aaa
HUAWEI_SMS_APP_SECRET=bbb
HUAWEI_SMS_SENDER_ID=ccc

运行时通过环境变量载入

docker run -d --name sms -p 80:80 \
-e "SMS_PROVIDER=aliyun" \
-e "ALIYUN_SMS_APP_KEY=aaa" \
-e "ALIYUN_SMS_APP_SECRET=bbb" \
-e "ALIYUN_SMS_REGION_ID=cn-hangzhou" \
-e "ALIYUN_SMS_SIGN_NAME=ccc" \
myapp:0.1

完整的项目可在这里查看。

示例项目代码

然后我们可以做如下测试，注意修改配置中的模版 ID 和环境变量，并根据自己的模版参数修改 params。

结语

对于老鸟来说，开发这个项目，可能根本不需要 1 个小时。对于规范的线上项目来说，还是缺少一些东西的，例如单元测试。大家的生产 API 服务是怎么样的？欢迎讨论！

这里的短信微服务只是抛砖引玉，其实所有的公有云 API 服务都可以一样的套用。1 小时上线一个微服务，剩下 7 小时划水刷掘金😄。

我是火眼君，愿我的写作，驱散心灵的孤单。

参考