🚀 Frappe 框架用户指南

本指南将帮助您了解如何安装、配置和使用 Frappe 框架，同时提供一些最佳实践，助您高效开发和维护 Web 应用程序。

🚀 快速开始

安装与配置

安装步骤

1. 下载安装包：从 Frappe 官方网站 下载适用于您操作系统的最新版本的安装包。
2. 环境准备：
   • 确保您的系统已安装 Python 3.7 或更高版本。
   • 安装 PostgreSQL 数据库，确保其版本为 10 或更高。
3. 安装脚本执行：运行下载的安装包中的 setup.py 脚本。根据提示完成安装过程。
4. 初始化配置：
   • 执行 frappe init 命令创建新项目。
   • 按照提示选择所需的应用模块并完成初始化设置。
5. 启动服务：使用命令 python3 -m frappe serve 启动 Frappe 服务，默认端口为 8000。

环境变量配置

• FRAPPE_SITE_URL：设置您的 Frappe 站点 URL，例如 http://localhost:8000。
• FRAPPE_SECRET_KEY：用于 API 调用的密钥生成，默认为随机字符串。
• DATABASE_URI：数据库连接 URI 格式为 postgresql://用户名:密码@主机/数据库名。

✨ 主要特性

Doctype 管理

创建与编辑文档类型

1. 创建新的 Doctype：
   • 在 Frappe 的 doc 目录下新建一个 JSON 文件，命名为 doctype_name.json。
   • 定义字段结构和验证规则。
2. 自定义 Doctype 表单：
   • 使用 HTML 和 JavaScript 创建表单界面，保存为 doctype_name.html。
   • 在 doctype_name.js 中添加事件监听器和自定义函数。
3. 启用与禁用文档类型：
   • 进入 Frappe 的系统设置，找到 Doctype 管理模块，选择所需操作。

文档类型示例

# 示例文档类型结构
{
  "doctype": "Customer",
  "fields": [
    {"label": "客户名称", "fieldname": "customer_name", "type": "Data"},
    {"label": "客户类型", "fieldname": "customer_type", "type": "Select", "options": ["Individual", "Company"]}
  ],
  "validation": {
    "required_fields": ["customer_name"],
    "unique": ["customer_email"]
  }
}

数据库交互

查询数据

1. 基本查询：
   • 使用 frappe.get_all 获取记录列表，支持过滤和排序。

   customers = frappe.get_all('Customer', filters={'customer_type': 'Individual'}, fields=['name', 'customer_name'])
   

2. 插入数据：
   • 调用 frappe.insert 方法添加新文档。

   new_customer = {
     "doctype": "Customer",
     "customer_name": "John Doe",
     "customer_type": "Individual"
   }
   frappe.insert(new_customer)
   

3. 更新数据：
   • 使用 frappe.update 方法修改现有记录。

   frappe.update('Customer', 'CUST-00001', {'email_id': 'john@example.com'})
   

4. 删除数据：
   • 调用 frappe.delete 方法删除指定文档。

   frappe.delete('Customer', 'CUST-00001')
   

表单验证与事件

自定义表单验证

// 示例验证函数
frappe.add_events("Customer", {
  "on_submit": function(doc) {
    if (!doc.customer_name) {
      throw new frappe.ValidationError("请输入客户名称");
    }
  }
});

📦 安装指南

安装步骤

1. 下载安装包：从 Frappe 官方网站 下载适用于您操作系统的最新版本的安装包。
2. 环境准备：
   • 确保您的系统已安装 Python 3.7 或更高版本。
   • 安装 PostgreSQL 数据库，确保其版本为 10 或更高。
3. 安装脚本执行：运行下载的安装包中的 setup.py 脚本。根据提示完成安装过程。
4. 初始化配置：
   • 执行 frappe init 命令创建新项目。
   • 按照提示选择所需的应用模块并完成初始化设置。
5. 启动服务：使用命令 python3 -m frappe serve 启动 Frappe 服务，默认端口为 8000。

环境变量配置

• FRAPPE_SITE_URL：设置您的 Frappe 站点 URL，例如 http://localhost:8000。
• FRAPPE_SECRET_KEY：用于 API 调用的密钥生成，默认为随机字符串。
• DATABASE_URI：数据库连接 URI 格式为 postgresql://用户名:密码@主机/数据库名。

💻 使用示例

基础用法

# 示例文档类型结构
{
  "doctype": "Customer",
  "fields": [
    {"label": "客户名称", "fieldname": "customer_name", "type": "Data"},
    {"label": "客户类型", "fieldname": "customer_type", "type": "Select", "options": ["Individual", "Company"]}
  ],
  "validation": {
    "required_fields": ["customer_name"],
    "unique": ["customer_email"]
  }
}

高级用法

# 高级查询示例
customers = frappe.get_all('Customer', filters={'customer_type': 'Individual'}, fields=['name', 'customer_name'], order_by='customer_name')

📚 详细文档

开发与进阶使用

插件开发指南

1. 创建插件结构：
   • 在项目根目录下新建 plugins 文件夹。
   • 创建插件主文件 plugin_name.js 和配置文件 plugin_name.json。
2. 注册自定义事件：

   frappe.plugins.register('my_plugin', {
     onReady: function() {
       console.log("插件已加载");
     }
   });
   

3. 扩展文档类型：
   • 在 doctype_name.js 中添加自定义方法和事件监听器。

API 使用说明

1. 获取访问令牌：

   curl --user admin:admin_pass http://localhost:8000/api/method/frappe.auth.get_token
   

2. 调用 REST API：

   curl -X GET "http://localhost:8000/api/resource/doctype/Customer"
   

3. 处理文件上传：

   curl -F file=@/path/to/image.jpg "http://localhost:8000/api/method/frappe.core.doctype.file_manager.upload_file"
   

最佳实践

性能优化

1. 数据库索引优化：
   • 在常用查询字段上创建索引，提高查询效率。

   CREATE INDEX idx_customer_name ON Customer(customer_name);
   

2. 缓存机制应用：
   • 使用 frappe.cache 模块缓存频繁访问的数据，减少数据库负载。
3. 异步任务处理：
   • 利用 Celery 等工具实现任务队列，提升系统响应速度。

安全注意事项

1. 权限控制：
   • 配置合适的角色和权限，确保最小化用户权限。

   frappe.add_perm("Customer", "Sales User", "read");
   

2. 日志记录：
   • 启用详细日志记录，监控系统行为并及时发现异常。
3. 定期安全审计：
   • 定期检查系统漏洞，更新组件至最新版本，确保系统安全。

通过遵循这些指南和最佳实践，您可以高效地使用 Frappe 框架开发和维护您的 Web 应用程序。