baoshi-was/文档/WAS项目规范.md

全局

PHP中长文本如无拼接必要性使用定界符(<<<)来声明
定义在模型或任意位置的常量都为业务逻辑服务，应该谨慎操作任何常量的变更

##命名

支持中文命名
    取消IDE中的Non-ASCII验证
    布尔值，返回布尔值的方法开头附加is
    复数，名词后跟“列"字
中文方法命名
    方法命名必须是动词、动词+名词、动词+名词+副词/定语结构；副词/定语放在后边可以以下划线分隔，例如：提交用户信息_后台运行()
    （超长的中文命名的方法，或不能以动词开头的方法，可能是方法本身的设计有误，尝试解耦设计，条件用参数等方式解决）
    模型中的方法可以使用名词，意为以方法当作属性字段
动作方法的命名
    用及物动词，不及物动词都可以，可以有副词在动词前后，不能是“名词前动词后”描述动作，或不能“名词+形容词”来描述动作
代码命名
    文件命名统一为驼峰单数命名且首字母大写(视图文件非大写)加对应功能块名称(例如：user模块：Model:User  controller：UserController service：UserService)
    数据库命名：表名为复数,多词使用下划线连接,中间表为单数(对于中间表而言建议根据首字母在26个英文字母中的顺序排列连接表)

##控制器

限制
    仅放请求
        页面
        API请求
        GET\POST等请求
        转发但可以单独作为请求的方法
方法命名
    显示页面（最后return为view()或直接显示的字符串的），命名以Page结尾。（框架标准CRUD不算）
    API请求，命名以Api结尾，路由放在apiLocal文件下
方法空间
    路由前缀应当对应同名控制器，一级前缀与控制器保持一致
模型对象的操作
    已有对象的，并且直接赋值模型对象的，不建立服务，直接使用 $对象->update(['字段名'=>值,'字段名2'=>值])

##验证

##服务

服务不能传入Request，不能返回Builder。以可以明确测试，以及明确缓存
注册
    必须在AppServiceProvicder中用app()->singleton绑定为单例；在控制器使用时可以在参数处依赖注入，也可以用app()实例化，使用app()实例化的，在其上用/**@var 类型 参数名 **/   进行注释以使其可以关联提示；服务中调用其他服务的，也用app()进行实例化并且用@var注释
    注册字符串名称大写开头
对象命名
    在控制器中调用时，如服务与控制器同前缀名的，服务器对象统一命名：$service，服务与控制器不同前缀名的不可以这样命名对象

##视图

路径文件夹与文件命名

##方法

方法应该按照其作用域来规定其属性，例如：对于后端而言仅供类内部调用的方法应该使用private，对于前端而言仅供其他函数调用的方法应该使用下划线(_)开头命名

##Request处理

参数调用
    （$request用链式调用(->)更好？）
    在调用处使用$request['input名称']这种方式，取得GET/POST请求参数；不需要重命名给新变量。

##页面

调用
    每个页面必须有一个同名控制器方法调用，一对一关系，不可以一个控制器调用多个页面。如有需要跳转的，由控制器进行redirect()方法跳转

##异常处理

页面调用
    throw new \Exception('错误描述')，即可自动调用错误页，一般不需主动调用
404
    仅在页面无法找到时调用（一般由框架自动调用），普通错误不可使用

##日志

日志统一使用app('LogService')->log()方法
日志记录发生在update, create, delete等增删改库的方法中必须使用；其他请况酌情使用
Excepiton异常时会自动日志，不需手动记录。除非要记录的标记不仅Request请求
第一，二个参数必须为 __METHOD__, __FUNCTION__ ；在闭包中，以字符串输入或转入参数的方式描述当前所在实际方法。
第三个参数为描述，以拼接的方式描述当前行为，必须描述当前关键标识字段（可以作为寻找问题时定位的）名，以及拼接出其值，API请求的，需要在进入请求时记录，记录关键标识，并拼接“request:”并用Json_encode()编码$request()->getContent()；有外部请求的，在外部请求完成后final{}中进行日志，记录关键标识，拼接"response:"，并且拼接Json_encode()“编码拼接$response->body()
插入新记录
    所有模型插入新记录时，如有多条循环插入情况，应当将该逻辑（循环外）用try catch final 包裹，日志记录写在final中，每条成功的放在一个数组里，由final一次请求记录（将成功数组JSON化）

##外部请求

必须用try{}catch(){}final{}处理，catch中必须处理请求失败的逻辑, final中日志记录response

##前端

布局，宽高等涉及样式呈现的，不使用HTML属性，使用bootstrap样式，bootstrap无法实现手动追加样式。（如 align="center"，使用class="text-center"，）

##JS

JS中双等号写成三等号（全等）

##模型

有外键关系的自字义自段，不添加至$appends，仅存在为getAttrbute()方法，如需要调用，在相应结果集添加with('')，前端在{!! !!}调用完默认结果集后，@foreach循环再追加这些自定义自段
使用$appends的属性，如有外键关系方法被调用，应当在之前增加"$this->外键方法->相应字段"这种方式优先调取(当作属性使用而不是方法)， 外部使用with(将关联表注明)
不能使用get开头的自定义方法，需要用到的用框架定义的getXXXAttribute()这种方式
模型关系的定义
    注意相互的从属关系：hasOne是父模型对于子模型的定义，belongsTo是子模型对于父模型的声明(一般而言：本表存在关联表的外键使用belongsTo,关联表存在本表的外键使用hasOne)
    建议：对于超长模型命名可忽略同级的前缀。(示例：user与userLog 模型关系可直接称之log)
关联查询
    慎用whereHas进行查询，whereHas生成的sql是 where exists 进行关联查询，当左表大于由右表时，左表就会成为性能瓶颈。where exists 会将右表查出来的结果同左表匹配。查出多少条就会匹配多少次。而且不走索引的全表扫描。
    建议先查出右表，再根据关联关系查左表。 

##控制台命令

将命令的实际逻辑写成Service方法，方便复用调用和测试

##数据库

字段类型，以_id为结尾的，或指向外部id的外键关系字段，必须是bigint

##GIT

每个需求描述完成时，要执行一个Commit并在描述中阐明。
每个需求修改提交一个commit

##测试

每个Service方法均需写一个对应的测试
每个Service在Tests，Services文夹下，建立对应名文件夹，一个方法对应一个测试文件
测试原则是自己生产自己销毁：使用数据不依赖环境数据，不影响环境数据
每个方法可以超过一个文件，如果N个是在基镜中需要配置相同假数据的，可以放在一个文件，不需要或其他假数据的，可以再做一个文件
同方法的多文件，在后缀Test之前用下划线_标注区分
windwos下调用测试，在命令行运行phpunit.bat ，空格后跟要测试的目标包(包可以phpunit.xml定义）

##缓存

缓存在service层以上使用,模型层内不使用
缓存在CacheService中，getOrExecute调用，第2个匿名函数放没有缓存时运行的实际逻辑
模型中的读取方法如需缓存，应在对应的Service中设置同名方法处理

##导出Excel表

默认应使用JSON方式，仅在以下两种情况用SQL：
> A 在之后发现性能跟不上等障碍
> B 在开发时明确发现必须用SQL的需求