Shopyo 技能

Shopyo 是一个模块化的 Flask 框架，专为可维护性、可扩展性及真实生产环境规模而设计。

项目结构

典型的 Shopyo 项目结构如下：

/project_root
├── app.py          # 入口文件，定义 create_app()
├── init.py         # 扩展初始化器（db、login_manager 等）
├── manage.py       # CLI 入口文件
├── config.py       # 基于配置环境（profile）的配置文件
└── modules/        # 模块化代码目录
    ├── box__default/
    │   ├── auth/
    │   └── settings/
    └── my_custom_module/

CLI 命令

# 环境配置
export SHOPYO_CONFIG_PROFILE=development
export FLASK_ENV=development
export FLASK_APP=app.py

# 新建项目
shopyo new myproject --demo
cd myproject
shopyo initialise

# 创建模块
shopyo startapp modulename [boxname]

# 创建 Box
shopyo startbox box__name

# 启动服务
shopyo run
flask run --debug

# 数据库操作
shopyo initialise   # 全新初始化（创建数据库、迁移文件、默认用户）
shopyo db migrate
shopyo db upgrade
shopyo clean        # 重置本地数据库

# 静态资源
shopyo collectstatic [module_path]  # 从模块中收集静态文件

# 其他命令
shopyo routes       # 显示所有路由
shopyo audit        # 检测项目潜在问题
shopyo rename old_name new_name  # 重命名模块

创建模块

shopyo startapp blog
# 或指定 Box
shopyo startapp blog box__ecommerce

生成以下目录结构：

modules/blog/
├── __init__.py
├── forms.py
├── global.py
├── info.json
├── models.py
├── view.py
├── static/
├── templates/
│   └── blog/
│       ├── blocks/
│       │   └── sidebar.html
│       ├── dashboard.html
│       └── index.html
└── tests/
    ├── test_blog_functional.py
    └── test_blog_models.py

info.json 结构

{
   "author": {"mail": "", "name": "", "website": ""},
   "display_string": "Page",
   "module_name": "page",
   "type": "show",
   "fa-icon": "fa fa-store",
   "url_prefix": "/page",
   "dashboard": "/dashboard"
}

模块视图模式

from shopyo.api.module import ModuleHelp

mhelp = ModuleHelp(__file__, __name__)
blueprint = mhelp.blueprint

@blueprint.route("/")
def index():
    context = mhelp.context()
    context.update({'message': 'Hello'})
    return mhelp.render('index.html', **context)

模型模式

from init import db
from shopyo.api.models import PkModel

class MyModel(PkModel):
    __tablename__ = 'mymodel'
    name = db.Column(db.String(100))

模板

继承基础模板：

{% extends "shopyo_base/main_base.html" %}
{% block content %}
Hello
{% endblock %}

使用 yo_render：

from shopyo.api.templates import yo_render

@blueprint.route("/demo")
def demo():
    return yo_render('blog/demo.html', {'key': 'value'})

Shopyo API

关键导入语句：

from shopyo.api.module import ModuleHelp, get_module, dispatch
from shopyo.api.models import PkModel
from shopyo.api.templates import yo_render
from shopyo.api.database import db
from shopyo.api.enhance import enhance_html

模块间通信

使用事件系统：

from shopyo.api.module import dispatch

# 触发事件
dispatch("user:registered", {"email": user.email})

# 监听事件
@dispatch("user:registered")
def send_welcome_email(email):
    pass

测试

pytest
pytest -v
pytest path/to/test.py
pytest --cov=shopyo
tox

global.py 模式

available_everywhere = {"x": 1}

configs = {
    "development": {"CONFIG_VAR": "DEVVALUE"},
    "production": {"CONFIG_VAR": "PRODVALUE"},
    "testing": {"CONFIG_VAR": "TESTVALUE"}
}

默认凭据

执行 shopyo initialise 后：

• 应用地址：http://localhost:5000
• 登录页面：http://localhost:5000/auth/login
• 邮箱： admin@domain.com
• 密码： pass

关键约定

• Box 文件夹名必须以 box__ 开头
• 模块相互隔离 —— 不得在模块间直接相互导入
• 模块间通信应使用事件系统（dispatch）
• 添加或移除模块后，需运行 shopyo initialise
• 静态文件统一收集至 static/modules/ 目录 —— 请勿直接编辑该目录下文件
• 使用 shopyo clean 可重置本地开发数据库