快速入门
需求
假如我们要开发一个商品模块，我们将它命名为 ItemBundle ，其包含了商品、sku、商品类型、标签，可以实现商品相关的增删改查。
环境说明
本文档是用的开发环境是官方的 docker 环境，点此查看，其他环境使用命令时请按需修改。
本文档所使用的 php artisan 命令，都需要进入容器内执行，进入容器的命令为：
docker exec -it ecshopx-dev-docker_espier-bloated-web_1 sh开发说明
在使用 Doctrine Orm 开发应用程序时，可以使用以下三种方式来启动开发：
Code First：首先要开发 Entity 类，然后将他们映射到数据库中
Model First：需要是用工具对（UML）进行建模，并从改模型生成数据库和 Entity 类
Database First：首先要设计数据表，然后根据数据表生成 Entity 类
Code First
此方式需要根据需求设计 Entity 类，设计时需要熟知 Doctrine Orm 注解，只要熟悉数据库设计即可，所以用这种方式效率更高。此方式具体开发流程如下：
一、设计 Entity 类
二、通过命令生成数据库迁移
php artisan doctrine:migrations:diff三、生成数据表
php artisan doctrine:migrations:migrate
Ecstore 和 Bbc 和此方式类似
Database First
此方式和 Database First 正好相反，先设计数据表，再生成 Entity 类。由于此方式不需要熟知 Doctrine Orm 注解，只要熟悉数据库设计即可，所以用这种方式效率更高。此方式具体开发流程如下：
一、采用数据库设计软件设计数据库 ER 图。
二、通过 ER 图生成的 SQL 创建数据表
三、通过命令生成实体
php artisan doctrine:mapping:import annotation --filter=DemoUser --namespace=ItemBundle\\Entities\\
--filter=DemoUser 中的 DemoUser 是想要生成的实体名，是数据表的大驼峰写法，不写 --filter 将会把数据库中所有的数据表都生成 Entity 放到 src/ItemBundle/Entities 目录中
本教程将采用 Database First 的方式。
设计数据库
根据需求，我们通过 Mysql Workbench 来设计 ER 图：
设计完 ER 图之后，在 Mysql Workbench 中可以通过 Database-> Forward Engineer 直接将 ER 图直接生成数据表。 为了方便讲解，我们将此 ER 图生成的 SQL 放在此处，方便大家直接创建数据库：
-- -----------------------------------------------------
-- Table `mydb`.`item_type`
-- -----------------------------------------------------
DROP TABLE IF EXISTS `mydb`.`item_type` ;
CREATE TABLE IF NOT EXISTS `mydb`.`item_type` (
`id` BIGINT NOT NULL,
`name` VARCHAR(255) NOT NULL COMMENT '名称',
`code` VARCHAR(64) NOT NULL COMMENT '编码',
`updated` INT(11) NOT NULL,
`created` INT(11) NULL,
PRIMARY KEY (`id`))
COMMENT = '类型表';
-- -----------------------------------------------------
-- Table `mydb`.`item`
-- -----------------------------------------------------
DROP TABLE IF EXISTS `mydb`.`item` ;
CREATE TABLE IF NOT EXISTS `mydb`.`item` (
`id` BIGINT NOT NULL AUTO_INCREMENT,
`item_type_id` BIGINT NOT NULL COMMENT '类型',
`name` VARCHAR(255) NOT NULL COMMENT '名称',
`price` DECIMAL(20,3) NOT NULL COMMENT '价格',
`created` INT(11) UNSIGNED NOT NULL COMMENT '创建时间',
`updated` INT(11) NULL COMMENT '最后更新时间',
PRIMARY KEY (`id`),
CONSTRAINT `fk_item_item_type`
FOREIGN KEY (`item_type_id`)
REFERENCES `mydb`.`item_type` (`id`)
ON DELETE NO ACTION
ON UPDATE NO ACTION)
COMMENT = '商品';
CREATE INDEX `fk_item_item_type_idx` ON `mydb`.`item` (`item_type_id` ASC);
-- -----------------------------------------------------
-- Table `mydb`.`sku`
-- -----------------------------------------------------
DROP TABLE IF EXISTS `mydb`.`sku` ;
CREATE TABLE IF NOT EXISTS `mydb`.`sku` (
`id` BIGINT NOT NULL AUTO_INCREMENT,
`name` VARCHAR(255) NOT NULL COMMENT '名称',
`price` DECIMAL(20,3) NOT NULL COMMENT '价格',
`created` INT(11) NOT NULL,
`updated` INT(11) NULL,
`store` VARCHAR(45) NULL COMMENT '库存',
`spec1` VARCHAR(45) NULL COMMENT '规格 1',
`spec2` VARCHAR(45) NULL COMMENT '规格 2\n',
`item_id` BIGINT NULL,
PRIMARY KEY (`id`),
CONSTRAINT `fk_sku_item1`
FOREIGN KEY (`item_id`)
REFERENCES `mydb`.`item` (`id`)
ON DELETE NO ACTION
ON UPDATE NO ACTION)
COMMENT = 'SKU';
CREATE INDEX `fk_sku_item1_idx` ON `mydb`.`sku` (`item_id` ASC);
-- -----------------------------------------------------
-- Table `mydb`.`tag`
-- -----------------------------------------------------
DROP TABLE IF EXISTS `mydb`.`tag` ;
CREATE TABLE IF NOT EXISTS `mydb`.`tag` (
`id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
`name` VARCHAR(60) NOT NULL COMMENT '标签名称',
`updated` INT(11) NOT NULL,
`created` INT(11) NULL,
PRIMARY KEY (`id`))
COMMENT = '标签';
-- -----------------------------------------------------
-- Table `mydb`.`item_tag`
-- -----------------------------------------------------
DROP TABLE IF EXISTS `mydb`.`item_tag` ;
CREATE TABLE IF NOT EXISTS `mydb`.`item_tag` (
`item_id` BIGINT NOT NULL,
`tag_id` BIGINT UNSIGNED NOT NULL,
PRIMARY KEY (`item_id`, `tag_id`),
CONSTRAINT `fk_item_tag_item1`
FOREIGN KEY (`item_id`)
REFERENCES `mydb`.`item` (`id`)
ON DELETE NO ACTION
ON UPDATE NO ACTION,
CONSTRAINT `fk_item_tag_tag1`
FOREIGN KEY (`tag_id`)
REFERENCES `mydb`.`tag` (`id`)
ON DELETE NO ACTION
ON UPDATE NO ACTION);
CREATE INDEX `fk_item_tag_tag1_idx` ON `mydb`.`item_tag` (`tag_id` ASC);
CREATE INDEX `fk_item_tag_item1_idx` ON `mydb`.`item_tag` (`item_id` ASC);生成实体类
我们可以通过命令行生成 Entity 类
php artisan doctrine:mapping:import annotation --namespace=ItemBundle\\Entities\\生成 Entity 成功后可以看到以下输出：
Importing mapping information from "mydb" entity manager
> writing /app/src/ItemBundle/Entities/Item.php
> writing /app/src/ItemBundle/Entities/ItemType.php
> writing /app/src/ItemBundle/Entities/Sku.php
> writing /app/src/ItemBundle/Entities/Tag.php以 ItemType 实体为例，打开 ItemType.php 可以看到以下内容：
<?php
namespace ItemBundle\Entities;
use Doctrine\ORM\Mapping as ORM;
/**
* ItemType
*
* @ORM\Table(name="item_type")
* @ORM\Entity
*/
class ItemType
{
/**
* @var int
*
* @ORM\Column(name="id", type="bigint", nullable=false)
* @ORM\Id
* @ORM\GeneratedValue(strategy="IDENTITY")
*/
private $id;
/**
* @var string
*
* @ORM\Column(name="name", type="string", length=255, nullable=false, options={"comment"="名称"})
*/
private $name;
/**
* @var string
*
* @ORM\Column(name="code", type="string", length=64, nullable=false, options={"comment"="编码"})
*/
private $code;
/**
* @var int
*
* @ORM\Column(name="updated", type="integer", nullable=false)
*/
private $updated;
/**
* @var int|null
*
* @ORM\Column(name="created", type="integer", nullable=true)
*/
private $created;
}生成实体类的 Getter 和 Setter
根据数据表生成的实体类，只有 private 的属性，我们还需要为其设置 Getter 和 Setter 方法，可以以下命令生成：
php artisan doctrine:generate:entities --filter=ItemType定义接口
一个接口对一个一条路由，一个路由对应一个控制器方法。
定义控制器
我们先来完成 ItemType 实体的增删改查操作。
先创建一个带有增删改查空方法的控制器：
<?php
//src/ItemBundle/Http/Api/V1/Action/ItemTypesController.php
namespace ItemBundle\Http\Api\V1\Action;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller as BaseController;
use Dingo\Api\Exception\StoreResourceFailedException;
class ItemTypesController extends BaseController
{
public function index(Request $request) {
return $this->response->array([]);
}
public function save(Request $request) {
return $this->response->array([]);
}
public function show(Request $request, $id) {
return $this->response->array([$id]);
}
public function update(Request $request, $id) {
}
public function destroy(Request $request, $id) {
}
}定义路由
<?php
//routes/api/item.php
$api->version('v1', function($api) {
$api->group(['namespace' => 'ItemBundle\Http\Api\V1\Action','middleware' => [], 'providers' => 'jwt'], function($api) {
$api->get('/item_types', ['name' => '获取商品类型列表', 'as' => 'item_types. list', 'uses'=>'ItemTypesController@index']);
$api->post('/item_types', ['name' => '创建商品类型', 'as' => 'item_types.save', 'uses'=>'ItemTypesController@save']);
$api->get('/item_types/{id}', ['name' => '获取商品类型详情', 'as' => 'item_types.show', 'uses'=>'ItemTypesController@show']);
$api->put('/item_types/{id}/', ['name' => '更新商品类型', 'as' => 'item_types.update', 'uses'=>'ItemTypesController@update']);
$api->delete('/item_types', ['name' => '删除商品类型', 'as' => 'item_types.destroy', 'uses'=>'ItemTypesController@destroy']);
});
});此时，可以通过浏览器访问 http://127.0.0.1:8080/api/item_types 获取商品类型列表接口。
定义接口文档
一、定义 ItemBundle 接口文档分组
基本信息：
<?php
//src/ItemBundle/Http/Api/V1/Swagger/Info.php
/**
* @SWG\Swagger(
* swagger="2.0",
* schemes={"http"},
* host="localhost",
* basePath="/espier/public/index.php/api/",
* @SWG\Info(
* version="1.0",
* title="商品相关接口",
* description="item api",
* ),
* )
*/接口标签
<?php
//src/ItemBundle/Http/Api/V1/Swagger/Tags.php
/**
* @SWG\Tag(
* name="ItemCrud",
* description="商品增删改查相关",
* )
*/
/**
* @SWG\Tag(
* name="ItemTag",
* description="商品标签",
* )
*/接口统一错误响应结构体：
<?php
//src/ItemBundle/Http/Api/V1/Swagger/ItemsErrorRespones.php
namespace src\GoodsBundle\Http\Api\V1\Swagger;
/**
* @SWG\Definition(type="object")
*/
class ItemsErrorRespones
{
/**
* @SWG\Property
* @var string
*/
public $message;
/**
* @SWG\Property
* @var string
*/
public $errors;
/**
* @SWG\Property(format="int32")
* @var int
*/
public $code;
/**
* @SWG\Property(format="int32")
* @var int
*/
public $status_code;
/**
* @SWG\Property
* @var string
*/
public $debug;
}二、定义具体接口的输入和输出
<?php
//src/ItemBundle/Http/Api/V1/Action/ItemTypesController.php
namespace ItemBundle\Http\Api\V1\Action;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller as BaseController;
use Dingo\Api\Exception\StoreResourceFailedException;
class ItemTypesController extends BaseController
{
/**
* @SWG\Get(
* path="/item_types",
* summary="获取商品类型列表",
* tags={"ItemType"},
* description="获取商品类型列表",
* operationId="index",
* @SWG\Response(
* response=200,
* description="成功返回结构",
* @SWG\Schema(
* @SWG\Property(
* property="data",
* type="array",
* @SWG\Items(
* type="object",
* @SWG\Property(property="status", type="stirng"),
* )
* ),
* ),
* ),
* @SWG\Response( response="default", description="错误返回结构", @SWG\Schema( type="array", @SWG\Items(ref="#/definitions/ItemsErrorRespones") ) )
* )
*/
public function index(Request $request) {
return $this->response->array([]);
}
/**
* @SWG\Post(
* path="/item_types",
* summary="新增商品类型",
* tags={"ItemType"},
* description="新增商品类型",
* operationId="save",
* @SWG\Parameter( name="name", in="formData", description="类型名称", required=true, type="string"),
* @SWG\Parameter( name="code", in="formData", description="类型描述", required=true, type="string"),
* @SWG\Response(
* response=200,
* description="成功返回结构",
* @SWG\Schema(
* @SWG\Property(
* property="data",
* type="array",
* @SWG\Items(
* type="object",
* @SWG\Property(property="id", type="integer"),
* @SWG\Property(property="name", type="string"),
* @SWG\Property(property="code", type="string"),
* )
* ),
* ),
* ),
* @SWG\Response( response="default", description="错误返回结构", @SWG\Schema( type="array", @SWG\Items(ref="#/definitions/ItemsErrorRespones") ) )
* )
*/
public function save(Request $request) {
return $this->response->array([]);
}
/**
* @SWG\Get(
* path="/item_types/{id}",
* summary="获取商品详情",
* tags={"ItemType"},
* description="获取商品类型列表",
* operationId="show",
* @SWG\Parameter( name="id", in="path", description="类型名称", required=true, type="string"),
* @SWG\Response(
* response=200,
* description="成功返回结构",
* @SWG\Schema(
* @SWG\Property(
* property="data",
* type="array",
* @SWG\Items(
* type="object",
* @SWG\Property(property="status", type="stirng"),
* )
* ),
* ),
* ),
* @SWG\Response( response="default", description="错误返回结构", @SWG\Schema( type="array", @SWG\Items(ref="#/definitions/ItemsErrorRespones") ) )
* )
*/
public function show(Request $request,$id) {
return $this->response->array([$id]);
}
/**
* @SWG\Put(
* path="/item_types/{id}",
* summary="更新商品类型",
* tags={"ItemType"},
* description="获取商品类型列表",
* operationId="update",
* @SWG\Parameter( name="id", in="path", description="类型名称", required=true, type="string"),
* @SWG\Parameter( name="name", in="formData", description="类型名称", required=false, type="string"),
* @SWG\Parameter( name="code", in="formData", description="类型描述", required=false, type="string"),
* @SWG\Response(
* response=200,
* description="成功返回结构",
* @SWG\Schema(
* @SWG\Property(
* property="data",
* type="array",
* @SWG\Items(
* type="object",
* @SWG\Property(property="status", type="stirng"),
* )
* ),
* ),
* ),
* @SWG\Response( response="default", description="错误返回结构", @SWG\Schema( type="array", @SWG\Items(ref="#/definitions/ItemsErrorRespones") ) )
* )
*/
public function update(Request $request, $id) {
}
/**
* @SWG\Delete(
* path="/item_types/{id}",
* summary="删除商品类型",
* tags={"ItemType"},
* description="删除商品类型",
* operationId="destroy",
* @SWG\Parameter( name="id", in="path", description="类型名称", required=true, type="string"),
* @SWG\Response(
* response=200,
* description="成功返回结构",
* @SWG\Schema(
* @SWG\Property(
* property="data",
* type="array",
* @SWG\Items(
* type="object",
* @SWG\Property(property="status", type="stirng"),
* )
* ),
* ),
* ),
* @SWG\Response( response="default", description="错误返回结构", @SWG\Schema( type="array", @SWG\Items(ref="#/definitions/ItemsErrorRespones") ) )
* )
*/
public function destroy(Request $request, $id) {
}
}三、接口文档
接口文档的生成请参阅 [接口文档生成和接口测试]
php artisan api:swagger --output=src/ItemBundle/Http/Api/V1 && php -S 0.0.0.0:8005 -t public/成功之后，将会看到以下界面：
实现商品类型的 CRUD
我们以 MVC 架构为基础，加入 Repository 模式 和 Service 模式来完成我们的开发。
第一步：新增相关类
新建与 ItemType 相关的 Service 和 Repository 类。
新建 ItemTypeSecvice 类：
//src/ItemBundle/Services/ItemTypeSercice.php
<?php
namespace ItemBundle\Services;
class ItemTypeService
{
}新建 ItemTypeRepository 类：
//src/ItemBundle/Repositories/ItemTypeRepository.php
<?php
namespace ItemBundle\Repositories;
use Doctrine\ORM\EntityRepository;
class ItemTypeRepository extends EntityRepository
{
}同时修改 ItemType 类与之相关联：
<?php
//src/ItemBundle/Entities/ItemType.php
namespace ItemBundle\Entities;
use Doctrine\ORM\Mapping as ORM;
/**
* ItemType
*
* @ORM\Table(name="item_type")
* @ORM\Entity(repositoryClass="ItemBundle\Repositories\ItemTypeRepository")
*/
class ItemType
{
//...
}第二步：确定调用关系
采用 Service 和 Repository 模式，相关类的调用关系为 Controller->Service->Repository 。
我们利用 Laravel 自带的依赖注入的方式，在 Controller 中新增构造方法来初始化 Service 类
<?php
//src/ItemBundle/Http/Api/V1/Action/ItemTypesController.php
namespace ItemBundle\Http\Api\V1\Action;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller as BaseController;
use Dingo\Api\Exception\StoreResourceFailedException;
use ItemBundle\Entities\ItemType;
use Dingo\Api\Exception\ResourceException;
use ItemBundle\Services\ItemTypeService;
class ItemTypesController extends BaseController
{
protected $itemTypeService;
public function __construct(ItemTypeService $itemTypeService)
{
$this->itemTypeService = $itemTypeService;
}
//...
}因为初始化 Repository 类需要特定的方法，所以在 ItemTypeSecvice 类中，我们需要手动初始化 Repository 类：
//src/ItemBundle/Services/ItemTypeSercice.php
<?php
namespace ItemBundle\Services;
use ItemBundle\Entities\ItemType;
class ItemTypeService
{
protected $itemTypeRepository;
public function __construct()
{
$this->itemTypeRepository = app('registry')->getManager('default')->getRepository(ItemType::class);
}
}第三步：编写逻辑
ItemTypeRepository 类
//src/ItemBundle/Repositories/ItemTypeRepository.php
<?php
namespace ItemBundle\Repositories;
use ItemBundle\Entities\ItemType;
use Doctrine\ORM\EntityRepository;
class ItemTypeRepository extends EntityRepository
{
public function store(ItemType $itemType)
{
$em = $this->getEntityManager();
$em->persist($itemType);
$em->flush();
return $itemType;
}
public function delete(ItemType $itemType)
{
$em = $this->getEntityManager();
$em->remove($itemType);
$em->flush();
return $itemType;
}
}ItemTypeSercice 类：
//src/ItemBundle/Services/ItemTypeSercice.php
<?php
namespace ItemBundle\Services;
use ItemBundle\Entities\ItemType;
class ItemTypeService
{
protected $itemTypeRepository;
public function __construct()
{
$this->itemTypeRepository = app('registry')->getManager('default')->getRepository(ItemType::class);
}
public function create($params)
{
$itemType = new ItemType();
$itemType->setName($params['name']);
$itemType->setCode($params['code']);
$itemType->setCreated(time());
return $this->itemTypeRepository->store($itemType);
}
public function update($id,$data)
{
$itemType = $this->itemTypeRepository->find($id);
if( !$itemType ) {
throw new ResourceException("未查询到更新数据");
}
$itemType->setName($data['name']);
$itemType->setCode($data['code']);
$itemType->setUpdated(time());
return $this->itemTypeRepository->store($itemType);
}
public function deleteById($id)
{
$itemType = $this->itemTypeRepository->find($id);
if( !$itemType ) {
throw new ResourceException("未查询到更新数据");
}
return $this->itemTypeRepository->delete($itemType);
}
public function findAll()
{
return $this->itemTypeRepository->findAll();
}
public function find($id)
{
return $this->itemTypeRepository->find($id);
}
public function toArray(ItemType $itemType)
{
return [
'id'=>$itemType->getId(),
'name'=>$itemType->getName(),
'code'=>$itemType->getCode(),
'created'=>$itemType->getCreated(),
'updated'=>$itemType->getUpdated(),
];
}
}控制器
<?php
//src/ItemBundle/Http/Api/V1/Action/ItemTypesController.php
namespace ItemBundle\Http\Api\V1\Action;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller as BaseController;
use Dingo\Api\Exception\StoreResourceFailedException;
use ItemBundle\Entities\ItemType;
use Dingo\Api\Exception\ResourceException;
use ItemBundle\Services\ItemTypeService;
class ItemTypesController extends BaseController
{
protected $itemTypeService;
public function __construct(ItemTypeService $itemTypeService)
{
$this->itemTypeService = $itemTypeService;
}
public function index(Request $request) {
$list = $this->itemTypeService->findAll();
foreach ($list as $itemType) {
$result[] = $this->itemTypeService->toArray($itemType);
}
return $this->response->array($result);
}
public function save(Request $request) {
$rules = [
'name' => ['required', '类型名称不能为空'],
'code' => ['required', '类型编码不能为空'],
];
$params = $request->all(array_keys($rules));
$error = validator_params($params, $rules);
if($error) {
throw new StoreResourceFailedException($error);
}
$itemType = $this->itemTypeService->create($params);
return $this->response->array(['id'=>$itemType->getId()]);
}
public function show(Request $request,$id) {
$itemType = $this->itemTypeService->find($id);
return $this->response->array($this->itemTypeService->toArray($itemType));
}
public function update(Request $request, $id) {
$rules = [
'name' => ['required', '类型名称不能为空'],
'code' => ['required', '类型编码不能为空'],
];
$params = $request->all(array_keys($rules));
$error = validator_params($params, $rules);
if($error) {
throw new StoreResourceFailedException($error);
}
$itemType = $this->itemTypeService->update($id,$params);
return $this->response->array(['status'=>'succ']);
}
public function destroy(Request $request, $id) {
$itemType = $this->itemTypeService->deleteById($id);
return $this->response->array(['status'=>'succ']);
}
}未完待续
Last updated
