YPPF 说明文档¶

目录¶

介绍¶

YPPF¶

Last commit GitHub forks

简体中文 | English

如何运行¶

环境要求¶

我们提供了搭建好的 Dev Container 开发环境，并强烈建议开发者和使用VSCode的初学者使用它。此外，我们也提供了在本地进行环境搭建的方法。

使用 VSCode Dev Container 进行开发¶

需要安装 Docker 和 VSCode 的 devcontainer 扩展。Linux 用户需要额外安装 docker compose。

在 VSCode 中，将主侧栏视图切换至远程资源管理器-开发容器，打开项目根目录。若 devcontainer 启动正常，可以看到：

vscode ➜ /workspace

至此，devcontainer 中相当于一个配置好的 Python 环境，并且无需自行配置 MySQL。

本地环境搭建¶

安装Python，在项目根目录启动终端
创建虚拟环境
```
python -m venv .env
```
其中.env可以是任何名称，该命令将生成.env文件夹作为虚拟环境，请勿重命名该文件夹。

激活虚拟环境

Windows

> .env\Scripts\activate
# 左侧出现(.env)表明成功激活，可通过以下方式检验
(.env) > where python
.env\Scripts\python.exe
(.env) > py -0p # 安装pylauncher的检验方式
Installed Pythons found by py Launcher for Windows
(venv)         .env\Scripts\python.exe *

Linux/macOS

$ source .env/bin/activate
# 左侧出现(.env)表明成功激活，可通过以下方式检验
(.env) $ which python
.env/bin/python

VSCode快捷激活

确认右下角Python环境切换到虚拟环境，如3.10.x('.env': venv)，并启动终端

安装环境依赖

(.env) $ pip install --require-virtualenv -r requirements.txt

初始化配置¶

创建数据库

CREATE DATABASE yppf CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

创建配置文件

我们使用config.json管理配置项。config_template.json是其完整模板，包含所有可选配置。

复制模板并重命名为config.json，在bash终端中，你也可以运行scripts/default_config.sh。
更新数据库配置

配置项

含义

示例

NAME

数据库名称

yppf

USER

数据库用户

root

PASSWORD

用户密码

（空）

HOST

数据库主机

127.0.0.1

PORT

数据库端口

3306

更新配置文件中django的数据库部分，更多配置项请参考各应用的config.py文件。

更新和迁移¶

在每次拉取项目代码后（包括初次下载），你都需要迁移数据库，使其与模型一致。

更新迁移文件
```
python manage.py makemigrations
```
这将在每个具有模型的应用的migrations文件夹生成一些迁移文件，请不要删除它们。
如果你怀疑某个应用（即文件夹）没有更新迁移文件，可以手动检查并更新它，直到不再变化：
$ python manage.py makemigrations xxx_app No change detected
执行迁移
```
python manage.py migrate
```
如果迁移失败，数据库将很可能难以恢复，此时最简单的办法是删库重建，执行scripts/remove_migrations.sh，并重新进行更新和迁移。

运行¶

# http://localhost:8000
python manage.py runserver
# http://localhost
python manage.py runserver 80
python manage.py runserver 0:80
python manage.py runserver 127.0.0.1:80
# http://ip:port
python manage.py runserver ip:port

执行任意一种命令以启动，直到你以Ctrl-C退出或关闭终端。启动后，便能通过对应网址访问，访问http://localhost:8000试试吧~

高级功能¶

生产/调试模式

将YPPF_DEBUG环境变量设置为true以开启调试模式。

调试模式便于使用，除非你打算在生产环境部署本项目，否则请设置为调试模式。
管理员

运行python manage.py createsuperuser，根据指示创建管理员账号。

管理员账号可用于登录后台/admin，试着访问http://localhost:8000/admin吧。

交互式执行（Django终端）

python manage.py shell

安装IPython后使用更便捷：

pip install ipython --require-virtualenv

常见问题¶

缺少模块，无法运行：ModuleNotFoundError: 'module_name'

可能因为缺少环境依赖，安装对应模块即可:
```
pip install module_name --require-virtualenv
```
如果使用requirement.txt安装后依然缺少，欢迎提出issue。
缺少环境变量，无法运行

通常提示os.environ找不到键，本项目的生产模式需要设置环境变量以保证安全，请切换到调试模式。
无法连接数据库：django.db.utils.OperationalError: (2003, "Can’t connect to MySQL server on ‘xxx’
- 配置错误：检查已经更新数据库配置并正确设置了config.json
- 若MySQL未启动，请先启动对应服务。
Django配置错误：ImproperlyConfigured

配置文件设置有误，请检查对应配置的config文件并修改。
缺少字段：Unknown column 'xx.xxx' in 'field list'

未执行迁移或模型变动未检出，请参考更新和迁移。必要时可以删库重建。

加入我们¶

您可以通过多种方式为本项目做出贡献，例如加入项目组、帮助改进代码或编写文档。即使您对编程一无所知，也能做出有意义的贡献，我们十分欢迎您向我们报告错误或提出改进建议。

报告错误和改进建议¶

若您在使用时遇到错误，或者有设计新功能的想法，请通过issue告诉我们。

若您在使用过程中遇到bug，可以详细描述触发错误的场景和操作，最好保证该错误可以复现。

若在运行代码时发生异常，请在报告中包含错误的traceback上下文信息，并尽量添加该文件的链接，以便查找问题。如有可能，提供能复现错误的代码片段是最直观的方法。

在提出任何建议前，我们希望您能查看是否已有类似提议，避免重复讨论。我们鼓励更具体明确的提案，这比泛泛而谈的交流更高效可行。

贡献代码¶

您应该使用Git管理代码。fork本仓库，并基于develop分支提交commit，最终提交拉取请求(PR, pull request)。你的任何说明信息都应优先使用中文。

你的 PR 必须满足以下要求，否则将不予受理：

标题清晰
查找并链接关联issue（如果存在）
通过自动化测试：python manage.py test
为每个新增接口编写文档

若您的 PR 品质良好，我们会保留您的详细提交信息，并欢迎您成为协作者。

贡献优质的Pull Request¶

好的 PR 在提交历史、代码质量、PR信息三方面都表现优秀，具体来说有以下特征：

线性历史：不含merge commit。若与最新的develop分支冲突，请使用rebase代替merge。
原子化提交：每个commit在功能上不可拆分，而非将大量修改堆砌到同一个commit中。
不含零碎修改：极小的修改应该被合并至相关commit中，而非单独提交。
commit信息有意义且易读
符合代码规范，如Google风格指南
代码可读性良好，注释和文档数量适宜
为新增接口编写测试，并提供导出信息（__all__）
同步更新环境说明文件和配置文件
为影响他人的改动申请 PR 标签：如删除、模型修改、环境和配置文件修改等。

致谢¶

贡献/参与者¶

感谢所有参与本项目的同学们和朋友们，是大家的帮助让 YPPF 越来越好！

如果觉得本项目对你有帮助，帮忙点个 Star 吧 ~

文档说明¶

可以通过以下方式生成文档：

安装sphinx
pip install sphinx
- 可能需要安装其它依赖，如``python-docs-theme``等
  pip install python-docs-theme
切换到docs目录
cd docs
从项目代码生成文档索引
sphinx-apidoc -e -d 2 -o source/yppf ../
- -e 表示每个文件生成独立的文件
- -d 设置目录树的最大深度
产生文档
make html

配置项	含义	示例
NAME	数据库名称	yppf
USER	数据库用户	root
PASSWORD	用户密码	（空）
HOST	数据库主机	127.0.0.1
PORT	数据库端口	3306