项目目录介绍及服务开发指南

代码目录结构

项目代码目录 说明

1

目录名称

说明

TcloudServer

根目录

apps

多服务目录

deploy

部署文件存放目录

library

通用库

apidoc.json

用于生产 apidoc 文档

docker-compose.yml

docker compose 配置文件

local_config.py

配置文件（本地）

Pipfile

pipenv 使用的 包管理 配置

public_config.py

通用配置文件

requirement.txt

pip -r 使用的 配置

apps

要添加新的模块或者服务，需要放置在本目录下。

2

目录名称

说明

author

用户以及鉴权相关

autotest

自动化测试

extention

工具

flow

流程

interface

接口测试

jobs

定时任务

message

站内信

project

项目

public

公共

tcdevices

云真机

ws

web socket

library

通用的方法提取出来分类放到对应文件中。

3

目录名称

说明

api

接口使用相关

notification.py

用来发送信息（站内信和企业微信通知）

oss.py

oss 相关

tlogger.py

日志相关

trpc.py

rpc 用于服务间调用，目前使用 http 协议

api

目录名称

说明

db.py

数据库相关，包括 db 和 model 定义

exceptions.py

异常定义

parse.py

request 请求参数处理

render.py

response 数据格式化

security.py

request 请求参数格式校验

tBlueprint.py

定义 blueprint，并对 get 和 delete 进行权限校验

tFlask.py

实现 TFlask 继承自 Flask，重写了 run 用于使用 gunicorn 启动，重写了 make_response 用于处理 response 格式化

tMiddleware.py

定义了用于处理 before_request 和 error_request 的中间函数

transfer.py

用于 格式化 数据库获取的结果

其他文件

  • notification.py

  • 包装了 发送站内信和发送微信消息 的方法，可以在当中添加其他发信方式。这里发送的两种方式 通过 其他服务发送。

class Notification:
    def __init__(self):
        self.public_trpc = Trpc('public')
        self.message_trpc = Trpc('message')

    def send_notification(self, user_ids, text, creator=None, send_type=None):
        # 发送站内信
        # 发送企业微信
        # 自定义发送方式

notification = Notification()

  1. 使用方法

from library.notification import notification

notification.send_notification([1,2,3], "helloworld")

  • oss.py

    用于 oss 上传 和 下载 文件 ,可以自定义添加其他方法。

  • tlogger.py

  • 日志相关,定义了 InfoFilter(logging.Filter) 作为 log 等级显示筛选。定义了 TloggerFormatter(logging.Formatter) 显示定制的 错误和警告信息。

  • 使用方法 : 在 flask app 初始化后 使用 logger_create()

    logger_create("hello-world", app)

  • trpc.py

  • 作为 rpc ，目前使用的是 http 协议进行服务间调用

  • 使用方法：在上面的 notification 中已经使用过了

from library.trpc import Trpc
# 使用服务名称获取对应的端口信息
public_trpc = Trpc('public')
public_trpc.requests('post', '/public/wxmessage', body={'user_ids': [1,2,4], 'text': "helloworld")

单个服务的项目结构，以 auth 为例子

  • 目前整个项目后端是 多服务 结构，每个服务负责的内容相对独立。

  • 由于项目是 前后端分离的，所以后端只提供接口供前端进行调用。

  • 整体架构是基于 flask、flask-sqlalchemy 进行构建的 非典型的 mvc 架构（model-view-controller）

目录结构

3

目录名称

说明

auth

服务名称/服务根目录

business

controller 所在目录，用于具体的逻辑构建

models

存放所有的 model，用于定义数据模型和数据库进行对应

settings

每个 服务独有 的配置信息

validatons

用于前面的 parse 和 security 的数据获取和数据校验 配置文件

views

存放所有 views

auth_require.py

鉴权相关

extentins.py

用于定义服务中使用的其他扩展

run.py

服务启动

4

创建一个简单地新的服务，以 auth 中的 user 为例子，选取 /v1/user/add 接口

创建目录结构

5

配置 config

apps/user/settings/config.py

try:
    from public_config import *
except ImportError:
    pass

# 端口号是自定义的，需要规划好扩展及其他的服务端口
PORT = 9999
# 服务名称与 目录名称 相同：user
SERVICE_NAME = 'user'

添加 extentions

apps/user/extentions.py

这个文件大部分是通用的库初始化的过程，主要有 初始化 validation，parse 等工具

import os
from os.path import join, abspath, dirname, splitext

import yaml

from library.api.parse import TParse
from library.api.security import Validation

current_path = dirname(abspath(__file__))

yml_json = {}

try:
    validate_yml_path = join(current_path, 'validations')
    for fi in os.listdir(validate_yml_path):
        if splitext(fi)[-1] != '.yml':
            continue
        with open(join(validate_yml_path, fi), 'rb') as f:
            yml_json.update(yaml.safe_load(f.read()))
except yaml.YAMLError as e:
    print(e)

v = Validation(yml_json)
validation = v.validation

p = TParse(yml_json)
parse_list_args = p.parse_list_args
parse_list_args2 = p.parse_list_args2
parse_json_form = p.parse_json_form
parse_pwd = p.parse_pwd

定义接口

/user/add

属性

值

路径

/user/add

方法

POST

参数

{"name":"hello", "nickname":"world", "password":"helloworld"}

首先定义 user 的 model

apps/user/models/users.py

from library.api.db import db, EntityWithNameModel

# 使用 含有 name 的模型进行继承，这样默认便会含有 name，creation_time, modified_time 。
# 数据库表名 与定义的模型名称的小写全拼相同，但驼峰式命名会转化为 _ 的格式。
# User == user, UserDetail == user_detail


# 定义 User 模型
class User(EntityWithNameModel):
    ACTIVE = 0
    DISABLE = 1

    nickname = db.Column(db.String(100), nullable=True)  # 昵称
    password = db.Column(db.String(100), nullable=False)  # 密码
    status = db.Column(db.Integer, default=ACTIVE)  # 状态，0：存在，1：删除

然后编写 用户添加数据库逻辑

apps/user/business/users.py

from flask import current_app

from apps.user.extentions import parse_pwd
from apps.user.models.users import User
from library.api.db import db


# 创建 UserBusiness
class UserBusiness(object):

    @classmethod
    def create_new_user_and_bind_roles(cls, username, nickname, password):
        # 传入 需要的参数 
        try:
            # 查询是否已经存在当前用户名的用户
            ret = User.query.filter(User.name == username, User.status == User.ACTIVE).first()
            if ret:
                return 103, None
            # 构建 User，使用 parse_pwd 加密 password 为密文
            n = User(
                name=username,
                nickname=nickname,
                password=parse_pwd(password)
            )
            # 使用 db 添加到数据库
            db.session.add(n)
            db.session.commit()
            return 0, None
        except Exception as e:
            current_app.logger.error(str(e))
            return 102, str(e)

添加 需要校验数据的 配置文件

apps/user/validations/users.yml

adduser:
  username:
    required: True
    type: basestring
  nickname:
    required: True
    type: basestring
  password:
    required: True
    type: basestring
  returnvalue:
    - username
    - nickname
    - password

然后编写 用户添加接口 逻辑

apps/user/views/users.py

from apps.user.business.users import UserBusiness
from apps.user.extentions import validation, parse_json_form
from library.api.tBlueprint import tblueprint

# 创建 blueprint
user = tblueprint("user", __name__, bpname="user", has_view=False)


# 定义 /add 路径 和 请求方法 POST
@user.route('/add', methods=['POST'])
@validation('POST:adduser') # 用于数据校验，主要从 validations/users.yml 中读取
def user_index_handler():
    # 从 validations/users.yml 中读取
    username, nickname, password = parse_json_form('adduser')
    ret, msg = UserBusiness.create_new_user_and_bind_roles(username, nickname, password)
    return {
        "code": ret,
        "data": [],
        "message": msg
    }

定义 app

apps/user/run.py

from apps.user.settings import config

if config.SERVER_ENV != 'dev':
    # 猴子补丁，用于 gunicorn 启动。
    from gevent import monkey
    monkey.patch_all()
else:
    pass

from apps.user.views.users import user
from library.api.tFlask import tflask


# 使用 create_app 创建 app
def create_app():
    app = tflask(config)
    register_blueprints(app)
    return app


# 注册 blueprint 到 app
def register_blueprints(app):
    app.register_blueprint(user, url_prefix="/v1/user")


# 启动应用
if __name__ == '__main__':
    create_app().run(port=config.PORT)

启动 app

   python3 -m apps.user.run

访问 POST

登录一下，需要启动全部服务，将返回的 token 填入 header 的 Authorization 中

再次访问

可以看到报错信息为 数据不对

后台报错信息

填写 请求的 Body (缺少参数)

类型为 json 格式

{
    "username": "test"
}

可以看到 返回为 缺少参数

后台报错信息

填写 完整的 body

{
    "username": "hello",
    "password": "helloworld",
    "nickname": "world"
}
Previous快速部署

Last updated

Was this helpful?