智简魔方文档

V10 开发规范

目录和文件

  • 目录使用小写+下划线,如admin/ 、 product_divert/

  • 类库、函数文件统一以.php为后缀,如app.php 、common.php

  • 类的文件名均以命名空间定义

并且命名空间的路径和类库文件所在路径一致,如ProductModel.php对应ProductModel类,命名空间app\common\model对应路径app/common/model/;

  • 类(包含接口和Trait)文件采用驼峰法命名(首字母大写)

类名(包括接口和Trait)和文件名保持一致,统一采用驼峰法命名(首字母大写),其它文件采用小写+下划线命名,如类文件app/common/logic/ConfigOptionsLogic.php对应ConfigOptionsLogic类,公共函数文件app/common.php;

目录结构

business  魔方V10业务系统

├─app           应用目录

│  ├─admin           后台

│  │  ├─controller      控制器目录

│  │  ├─model           模型目录(业务逻辑写这里或逻辑类里)

│  │  ├─validate        验证器目录

│  ├─home            前台

│  │  ├─controller      控制器目录

│  │  ├─model           模型目录

│  │  ├─validate        验证器目录

│  ├─common          公共目录

│  │  ├─logic           逻辑类目录

│  │  ├─model           模型目录(前后台通用模型方法写这里面的model类)

│  ├─command         命令行目录

│  │  ├─Cron.php        系统默认定时任务文件

│  ├─exception          异常处理目录

│  ├─http           网关目录

│  │  ├─middleware      中间件目录

│  ├─common.php         公共函数文件(写函数注释,比较通用的方式先写好,如curl)

│  ├─middleware.php     中间件定义文件

├─cron                   定时任务

│  ├─cron.php            定时任务

├─config                全局配置目录

│  ├─app.php            应用配置

│  ├─cache.php          缓存配置

│  ├─console.php        控制台配置

│  ├─cookie.php         Cookie配置

│  ├─database.php       数据库配置

│  ├─filesystem.php     文件磁盘配置

│  ├─lang.php           多语言配置

│  ├─log.php            日志配置

│  ├─middleware.php     中间件配置

│  ├─route.php          URL和路由配置

│  ├─session.php        Session配置

│  ├─trace.php          Trace配置

│

├─route                  路由目录

│  ├─admin.php          后台路由

│  ├─home.php           前台路由

│

├─public                WEB目录(对外访问目录)

│  ├─index.php          入口文件

│  ├─{DIR_ADMIN}   后台模板目录(部署时使用后台目录变量)

│  ├─home         前台模板目录

│  ├─plugins         插件目录

│  ├─.htaccess          用于apache的重写

│

├─runtime               应用的运行时目录(可写,可定制)

├─vendor                Composer类库目录
  • 使用模型方式进行增删改查

写在app/common/model/下(前后台通用);例子:创建订单,建立文件app/common/model/OrderModel.php,create()创建订单;

  • 逻辑类,写在app/common/logic/下,例子:ProvisionLogic.php服务模块逻辑类等

函数和类、属性命名

  • 类的命名采用驼峰法(首字母大写),例如 User、UserType

  • 函数的命名使用小写字母和下划线(小写字母开头)的方式

例如 get_client_ip,公共函数文件app/common.php统一使用此方式命名;

  • 方法的命名使用驼峰法(首字母小写),例如 getUserName

  • 属性的命名使用驼峰法(首字母小写),例如 tableName、instance

  • 特例:以双下划线__打头的函数或方法作为魔术方法

例如 __call 和 __autoload;

  • 变量的命名使用驼峰法(首字母小写)

例如 $tableName。实例化类的变量和类名同名,大驼峰变量,例如:$User。逻辑类中的变量加后缀,例如:$SmsLogic。

常量和配置

  • 常量以大写字母和下划线命名,例如 APP_PATH

  • 配置参数以小写字母和下划线命名,例如 url_route_on 和url_convert

  • 环境变量定义使用大写字母和下划线命名,例如APP_DEBUG

数据库表说明

  • 数据库表采用 innodb引擎

  • utf8mb4字符集

  • 带自增主键

  • 有默认值(text这类类型除外)

  • 字符串类型的一定要有默认值,不要用NULL

  • 创建表一定要有字段说明

  • 日期存时间戳,所以日期类型用int(11)

  • 价格相关数据用 decimal(10,2),有的可能需要更高的精度decimal(10,5)

  • 适当添加索引,参考数据库表索引建立

  • 数据库里不使用存储过程、视图、函数、触发器、事件(否则维护麻烦)

  • 数据表和字段采用小写加下划线方式命名

并注意字段名不要以下划线开头,例如 idcsmart_accounts表和 amount_out字段,不建议使用驼峰和中文作为数据表及字段命名。

  • 数据库表不使用外键

  • 数据库用5.7,开启严格模式

  • 表与表关联的ID要带表名。例如:product_id

  • 表或字段读取不需要写as,例如client c

搜索和分页参数名

搜索参数名:$keywords
分页:$page
条数:$limit
排序:$orderby
升序降序:$sort desc asc ;

智简魔方代码规范

  • 控制器方法中尽量只写传参,验证、json返回,业务逻辑写在model里,或者逻辑类里

  • 控制器里只有接口方法

不要写多余的方法在控制器文件中,其他方法、逻辑写model里或者逻辑类里、或者公共函数里;

  • 除接口返回json格式外,其他函数方法一律返回单个值,或者数组

  • 更改框架核心代码、基类控制器时,一定要商量,并写好更改的文档,做好记录

  • 函数超过两个参数,采用数组方式传入;(讨论:这个涉及到后面可能会不断的增加传入参数)

  • 公共函数里 尽量不使用数据库操作,用use 引用模型类

  • 不要实例化控制器

  • 变量赋值运算前后添加空格

例如:

$td .= '</td>'
  • 类,函数名后面的花括号紧跟后面,换行写

例如:

class CartController extends CommonController
{

注释格式

  1. api接口和类里面方法的注释格式
/**
 * @title title
 * @desc desc
 * @author author
 * @version version
 * @url url
 * @method method
 * @namespace namespace
 * @param type name default desc validate
 * @return type name default desc
 */

如果当前default没有的话可以用 - 占位,validate没有的话可以不写

return的参数如果仅返回单个数据并无变量名称是type之后的参数可以不填

方法的param如果有顺序的话需要按顺序写

param和return后面的参数以空格隔开,参数的内容之中不能存在空格

例如

/**
 * @title 节点分组列表
 * @desc 节点分组列表
 * @author hh
 * @version v1
 * @url node_groups
 * @method GET
 * @param int $page 1 页数
 * @param int $per_page 20 每页条数
 * @param string $orderby id 排序(id,name)
 * @param string $sort desc 排序方向
 * @param string $search - 搜索
 * @param string $list_type page 获取类型(all,page),all会忽略页数直接返回所有
 * @return int $data[].id - 节点分组ID
 * @return string $data[].name - 节点分组名称
 * @return string $data[].description - 节点分组名称
 * @return string $data[].create_time - 创建时间
 * @return int $data[].node[].id - 使用节点ID
 * @return string $data[].node[].name - 使用节点名称
 * @return int $meta.total - 总条数
 * @return int $meta.total_page - 总页数
 * @return int $meta.page - 当前页
 * @return int $meta.per_page - 每页条数
 */
  1. 公共方法的注释格式
/**
 * @title title
 * @desc desc
 * @author author
 * @version version
 * @param type name default desc validate
 * @return type name default desc
 */

如果当前default没有的话可以用 - 占位,validate没有的话可以不写

return的参数如果仅返回单个数据并无变量名称是type之后的参数可以不填

方法的param如果有顺序的话需要按顺序写

param和return后面的参数以空格隔开,参数的内容之中不能存在空格

/**
 * @title 获取客户端IP地址
 * @desc 获取客户端IP地址
 * @author hh
 * @version v1
 * @param integer $type 返回类型0返回IP地址1返回IPV4地址数字
 * @param boolean $adv 是否进行高级模式获取(有可能被伪装)
 * @return string
 */

其他

  • 前端传值用json,后端统一返回json格式数据

  • 返回数组一律转化为对象

  • 所有函数都需要写清楚文档

  • 状态码:200返回正确 400返回错误 302重定向 500系统错误,401登录失效,404无权限

状态码含义
200请求成功
302重定向
400请求错误
401登录失效
404无权限
500系统错误

数据返回格式

字段类型说明
statusinteger业务状态码
msgstring响应消息
dataobject响应数据
{

"status":200/400/302/500,

"msg":"success message",

"data":{

}

}
  • 控制器的函数中不要写参数

  • php使用7.4

  • 注意不要使用php 语言结构或函数 来作为方法、变量

  • 公共语言 写在后台的语言文件; 键值 小写+下划线

语言文件写法

success_message => '请求成功'

字段统一

备注字段统一用 notes varchar(1000)

支付字段统一用 gateway

产品id统一用 product_id

用户id统一用 client_id

计费周期字段统一用 billing_cycle